{"id":37071948,"url":"https://github.com/pokeyaro/shellkit","last_synced_at":"2026-01-14T08:26:53.044Z","repository":{"id":301104745,"uuid":"1008149228","full_name":"pokeyaro/shellkit","owner":"pokeyaro","description":"Unix shell simulator in Python with libc, syscalls, and i18n manuals.","archived":false,"fork":false,"pushed_at":"2025-06-27T12:19:57.000Z","size":314,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-27T20:12:41.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ShellKit/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pokeyaro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T05:33:31.000Z","updated_at":"2025-08-13T06:02:30.000Z","dependencies_parsed_at":"2025-06-25T07:28:00.369Z","dependency_job_id":"8f6f578f-982b-4ce3-a2ca-ed4424cbea2b","html_url":"https://github.com/pokeyaro/shellkit","commit_stats":null,"previous_names":["pokeyaro/shellkit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pokeyaro/shellkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pokeyaro%2Fshellkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pokeyaro%2Fshellkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pokeyaro%2Fshellkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pokeyaro%2Fshellkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pokeyaro","download_url":"https://codeload.github.com/pokeyaro/shellkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pokeyaro%2Fshellkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:16:59.381Z","status":"ssl_error","status_checked_at":"2026-01-14T08:13:45.490Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T08:26:52.556Z","updated_at":"2026-01-14T08:26:53.031Z","avatar_url":"https://github.com/pokeyaro.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"learning\"\u003e\u003c/a\u003eLearning and didactic tools"],"sub_categories":[],"readme":"# 🐚 ShellKit (libc + pysh)\n\n\u003e Learn how `echo` works from shell to syscall — all in one Python playground.\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)\n[![PyPI version](https://img.shields.io/pypi/v/shellkit)](https://pypi.org/project/shellkit/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](https://github.com/pokeyaro/shellkit)\n[![Languages](https://img.shields.io/badge/languages-EN%20%7C%20中文%20%7C%20日本語%20%7C%20한국어-brightgreen)](./examples/)\n[![CI](https://github.com/pokeyaro/shellkit/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/pokeyaro/shellkit/actions/workflows/ci.yml)\n\n**English** | [简体中文](./README_zh.md) | [日本語](./README_ja.md) | [한국어](./README_ko.md)\n\n---\n\n## 📖 Overview\n\n`ShellKit` is a Unix-like educational terminal toolkit consisting of two main components:\n\n* **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.\n* **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.\n\nRuns on both `macOS` and `Linux`, supporting `Arm64` and `Intel x86_64` architectures.\n\n\n## ✨ Features\n\n### Pysh\n\n* 🧠 Built-in commands (`cd`, `echo`, `pwd`, `env`, etc.)\n* 🧵 Multilingual support with full manuals (EN/CH/JP/KR)\n* 🔍 Cross-layer tracing: from command parsing → libc functions → C-level syscalls\n* 🧹 Composable REPL execution model\n* 🔌 Pluggable command registration system\n\n### Libc\n\n* 📨 Custom `printf` engine with `%s`, `%d`, `%f` format specifiers and escape sequences\n* 📜 Native syscall bridge (Python ↔ C) via `syscall/syslib.so`\n* 🧪 Unit-tested via `pytest`, with benchmarks for key libc behaviors\n\n\n## 📦 Installation\n\n\u003e Requires `Python 3.10` or newer\n\nInstall via `pip`:\n\n```bash\npip install shellkit\n```\n\nAfter installation, launch the interactive shell with:\n\n```bash\npysh\n```\n\n\n## 🚀 Usage\n\n```bash\npysh [options]\n```\n\n### CLI Options\n\n| Option          | Description                                                    |\n| --------------- | -------------------------------------------------------------- |\n| `--command`     | Run a single command                                           |\n| `--no-banner`   | Skip the startup banner                                        |\n| `--no-reminder` | Disable rest reminder messages                                 |\n| `--quiet`       | Quiet mode with minimal output                                 |\n| `--safe`        | Enable safety mode (blocks dangerous commands like `rm -rf /`) |\n| `--debug`       | Enable shell-level debug output                                |\n| `--trace-echo`  | Trace `echo`/`printf` calls down to `libc` syscall layer       |\n\nFor more, run:\n\n```bash\npysh --help\n```\n\n\n## 📚 Examples \u0026 Tutorials\n\nWant to see ShellKit in action? Check out our comprehensive examples:\n\n→ **[Examples \u0026 Demos](./examples/README.md)** - Real terminal sessions from basic to advanced features\n\n*Complete with multilingual demos, debugging tutorials, and advanced printf formatting!*\n\n\n## 📦 Project Structure (partial)\n\n```text\nshellkit/\n├── native/         # C code for native syscall implementation (builds syslib.so)\n├── shellkit/       # Main package\n│   ├── syscall/    # Python-side syscall wrappers via ctypes\n│   ├── libc/       # Custom libc (printf, write, exit)\n│   ├── shell/      # Core engine, built-in commands, runtime, REPL\n│   ├── inspector/  # Debugging and tracing tools\n│   └── i18n/       # Multilingual dictionaries and support\n├── benchmarks/     # Performance benchmarks\n├── examples/       # Usage examples and demo logs\n└── tests/          # Test suite\n```\n\n\n## 🥉 Platform Support for syslib.so\n\n| Platform                   | Supported  | Notes                                          |\n| -------------------------- |------------| ---------------------------------------------- |\n| **Linux x86\\_64**          | ✅ Yes     | Uses `rax = 1` + `syscall`                     |\n| **Linux ARM64**            | ✅ Yes     | Uses `x8 = 64` + `svc #0`                      |\n| **macOS Intel (x86)**      | ✅ Yes     | Uses `rax = 0x2000004` + `syscall`             |\n| **macOS ARM64 (M1/M2/M3)** | ✅ Yes     | Uses `syscall(SYS_write, ...)` (soft wrapper)  |\n| **Windows**                | ❌ No      | Not supported; lacks a unified `syscall()` ABI |\n\n\n## 🧭 Roadmap\n\nShellKit is stable and usable, but we plan to explore some exciting features in future releases:\n\n- 🔌 **Plugin System**: Allow users to register custom builtin commands, aliases, and functions\n- 🧠 **Deep Thinking Mode**: Experimental tracing into native syscalls (e.g. eBPF or low-level syscall capture)\n- 🧳 **Persistent Profiles**: Save environment variables, shell history, and custom setups\n- 🧪 **More Built-ins**: Extend shell with commands like `ls`, `cat`, `grep`\n- 💡 **Multiline Script Execution**: Support running multi-line commands or script blocks in one go\n\nIf 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). \\\nWe welcome all contributors — from feature suggestions to actual code!\n\n\u003e 💬 Turn your interest into contribution — ShellKit grows better with community voices.\n\n\n## 📌 Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n\n## 📜 License\n\nMIT License. See [LICENSE](./LICENSE) for details.\n\n\n## 🤝 Acknowledgments\n\nInspired by the spirit of classic Unix shells. \\\nThanks to all system programmers and terminal geeks who paved the way.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpokeyaro%2Fshellkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpokeyaro%2Fshellkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpokeyaro%2Fshellkit/lists"}