https://github.com/pokeyaro/shellkit
Unix shell simulator in Python with libc, syscalls, and i18n manuals.
https://github.com/pokeyaro/shellkit
Last synced: 6 months ago
JSON representation
Unix shell simulator in Python with libc, syscalls, and i18n manuals.
- Host: GitHub
- URL: https://github.com/pokeyaro/shellkit
- Owner: pokeyaro
- License: mit
- Created: 2025-06-25T05:33:31.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-27T12:19:57.000Z (about 1 year ago)
- Last Synced: 2025-11-27T20:12:41.673Z (7 months ago)
- Language: Python
- Homepage: https://pypi.org/project/ShellKit/
- Size: 307 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - ShellKit - Unix-like educational terminal toolkit consisting of: Libc (simulation of syscall, write, printf and more) and Pysh (interactive shell). (<a name="learning"></a>Learning and didactic tools)
- awesome-cli-apps - ShellKit - Unix-like educational terminal toolkit consisting of: Libc (simulation of syscall, write, printf and more) and Pysh (interactive shell). (<a name="learning"></a>Learning and didactic tools)
README
# ๐ ShellKit (libc + pysh)
> Learn how `echo` works from shell to syscall โ all in one Python playground.
[](https://www.python.org)
[](https://pypi.org/project/shellkit/)
[](./LICENSE)
[](https://github.com/pokeyaro/shellkit)
[](./examples/)
[](https://github.com/pokeyaro/shellkit/actions/workflows/ci.yml)
**English** | [็ฎไฝไธญๆ](./README_zh.md) | [ๆฅๆฌ่ช](./README_ja.md) | [ํ๊ตญ์ด](./README_ko.md)
---
## ๐ Overview
`ShellKit` is a Unix-like educational terminal toolkit consisting of two main components:
* **Libc**: A Python-based simulation of core C library calls such as `syscall`, `write`, and `printf`. It walks through the transition from user space to kernel space.
* **Pysh**: An interactive shell built on top of `Libc`, featuring internal commands, REPL execution, cross-layer tracing, and multilingual support. Designed for system developers and terminal enthusiasts.
Runs on both `macOS` and `Linux`, supporting `Arm64` and `Intel x86_64` architectures.
## โจ Features
### Pysh
* ๐ง Built-in commands (`cd`, `echo`, `pwd`, `env`, etc.)
* ๐งต Multilingual support with full manuals (EN/CH/JP/KR)
* ๐ Cross-layer tracing: from command parsing โ libc functions โ C-level syscalls
* ๐งน Composable REPL execution model
* ๐ Pluggable command registration system
### Libc
* ๐จ Custom `printf` engine with `%s`, `%d`, `%f` format specifiers and escape sequences
* ๐ Native syscall bridge (Python โ C) via `syscall/syslib.so`
* ๐งช Unit-tested via `pytest`, with benchmarks for key libc behaviors
## ๐ฆ Installation
> Requires `Python 3.10` or newer
Install via `pip`:
```bash
pip install shellkit
```
After installation, launch the interactive shell with:
```bash
pysh
```
## ๐ Usage
```bash
pysh [options]
```
### CLI Options
| Option | Description |
| --------------- | -------------------------------------------------------------- |
| `--command` | Run a single command |
| `--no-banner` | Skip the startup banner |
| `--no-reminder` | Disable rest reminder messages |
| `--quiet` | Quiet mode with minimal output |
| `--safe` | Enable safety mode (blocks dangerous commands like `rm -rf /`) |
| `--debug` | Enable shell-level debug output |
| `--trace-echo` | Trace `echo`/`printf` calls down to `libc` syscall layer |
For more, run:
```bash
pysh --help
```
## ๐ Examples & Tutorials
Want to see ShellKit in action? Check out our comprehensive examples:
โ **[Examples & Demos](./examples/README.md)** - Real terminal sessions from basic to advanced features
*Complete with multilingual demos, debugging tutorials, and advanced printf formatting!*
## ๐ฆ Project Structure (partial)
```text
shellkit/
โโโ native/ # C code for native syscall implementation (builds syslib.so)
โโโ shellkit/ # Main package
โ โโโ syscall/ # Python-side syscall wrappers via ctypes
โ โโโ libc/ # Custom libc (printf, write, exit)
โ โโโ shell/ # Core engine, built-in commands, runtime, REPL
โ โโโ inspector/ # Debugging and tracing tools
โ โโโ i18n/ # Multilingual dictionaries and support
โโโ benchmarks/ # Performance benchmarks
โโโ examples/ # Usage examples and demo logs
โโโ tests/ # Test suite
```
## ๐ฅ Platform Support for syslib.so
| Platform | Supported | Notes |
| -------------------------- |------------| ---------------------------------------------- |
| **Linux x86\_64** | โ
Yes | Uses `rax = 1` + `syscall` |
| **Linux ARM64** | โ
Yes | Uses `x8 = 64` + `svc #0` |
| **macOS Intel (x86)** | โ
Yes | Uses `rax = 0x2000004` + `syscall` |
| **macOS ARM64 (M1/M2/M3)** | โ
Yes | Uses `syscall(SYS_write, ...)` (soft wrapper) |
| **Windows** | โ No | Not supported; lacks a unified `syscall()` ABI |
## ๐งญ Roadmap
ShellKit is stable and usable, but we plan to explore some exciting features in future releases:
- ๐ **Plugin System**: Allow users to register custom builtin commands, aliases, and functions
- ๐ง **Deep Thinking Mode**: Experimental tracing into native syscalls (e.g. eBPF or low-level syscall capture)
- ๐งณ **Persistent Profiles**: Save environment variables, shell history, and custom setups
- ๐งช **More Built-ins**: Extend shell with commands like `ls`, `cat`, `grep`
- ๐ก **Multiline Script Execution**: Support running multi-line commands or script blocks in one go
If you're interested in any of these โ or have other ideas in mind โ feel free to [open a discussion](https://github.com/pokeyaro/shellkit/discussions) or [submit a pull request](https://github.com/pokeyaro/shellkit/pulls). \
We welcome all contributors โ from feature suggestions to actual code!
> ๐ฌ Turn your interest into contribution โ ShellKit grows better with community voices.
## ๐ Changelog
See [CHANGELOG.md](./CHANGELOG.md) for version history.
## ๐ License
MIT License. See [LICENSE](./LICENSE) for details.
## ๐ค Acknowledgments
Inspired by the spirit of classic Unix shells. \
Thanks to all system programmers and terminal geeks who paved the way.