🐚 ShellKit (libc + pysh)

Learn how echo works from shell to syscall — all in one Python playground.

English | 简体中文 | 日本語 | 한국어

---

📖 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:

pip install shellkit

After installation, launch the interactive shell with:

pysh

🚀 Usage

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:

pysh --help

📚 Examples & Tutorials

Want to see ShellKit in action? Check out our comprehensive examples:

→ Examples & Demos - Real terminal sessions from basic to advanced features

Complete with multilingual demos, debugging tutorials, and advanced printf formatting!

📦 Project Structure (partial)

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 or submit a pull request.
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 for version history.

📜 License

MIT License. See LICENSE for details.

🤝 Acknowledgments

Inspired by the spirit of classic Unix shells.
Thanks to all system programmers and terminal geeks who paved the way.