# kidshell
A [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) shell that is resilient in the face of _childish expectations_.
> 🔒 **Security First**: kidshell implements comprehensive security measures to protect young users.
See [SECURITY.md](SECURITY.md) for details on our security features and vulnerability reporting.
## Quick Start
```bash
# Run without installation (recommended)
uvx kidshell
```
Once launched, think *"What would a child do?"* and try:
- **Colors**: `blue`, `red`, `green` (or any color name)
- **Emojis**: `bread`, `cat`, `star` (anything with an emoji)
- **Ranges**: `0...100...1` or `0...10000...10...0.01`
- **Math**: `1+1`, `pi`, `c`, `g`, `h`, `tau` (constants and expressions)
- **Symbolic algebra**:
- `x`, `x + 3`, `x = 2`, then `x + 3` again
- Define multiple variables: `x + y - z`
- **Just press Enter** - see what happens!
- **Smash the keyboard** - it handles gibberish gracefully
## Installation Options
### For Parents and IT Admin
```bash
# Fastest - no installation needed
uvx kidshell
# Traditional pip install
pip install kidshell
# Or any of these valid ways of installing kidshell as a reusable command
pipx install kidshell # global in PATH
uv tool install kidshell # global in PATH
# or into your preferred venv
python -m venv OR uv venv
source .venv/bin/activate
uv pip install kidshell # into an isolated venv
```
### For Developers
See [DEVELOPMENT.md](DEVELOPMENT.md) for the complete development guide.
**Quick start:**
```bash
git clone https://github.com/anthonywu/kidshell.git
cd kidshell
just setup # Creates venv, installs deps
source .venv/bin/activate
just run # Run kidshell
```
## Custom Data Configuration
kidshell supports custom input→output mappings stored in platform-specific directories:
```bash
# Edit custom data
kidshell config # Opens editor with example.json
kidshell config edit mydata.json # Create/edit specific file
kidshell config list # List all data files
kidshell config info # Show config locations
```
Data files are JSON with custom mappings:
```json
{
"hello": "👋",
"world": "🌍",
"cat": "🐱",
"dog": "🐕"
}
```
## Project Structure
```
kidshell/
├── src/kidshell/ # Source code
│ ├── cli/ # CLI and REPL
│ ├── core/ # Core services
│ └── frontends/ # UI frontends
├── tests/ # Test files
├── justfile # Development commands
└── pyproject.toml # Project configuration
```
## Roadmap
1. 👥 Multiple profiles for N users in your family/classroom
1. 🖥 Run in browser or host at a web site
1. 📥 Load user/family configs from public https URLs
1. 📖 Dictionary database/API integration for spelling validation
1. 💬 Translation lookups for multilingual households
1. 🔊 Text-to-speech integration via [localtalk](https://github.com/anthonywu/localtalk)
1. ✨ Local/offline AI magic, if applicable and reasonably to introduce to children.
1. 🏞 Local/offline image generation with content moderation
1. 🧮 Expand usage of math libraries
1. 🌐 More UI languages
## Security
kidshell takes security seriously, especially given our young user base. We implement:
- **Path traversal protection** preventing unauthorized file system access
- **Safe JSON processing** without code execution risks
- **Subprocess security** with command validation and safe defaults
- **Secure file operations** confined to user-specific directories
For detailed security information, vulnerability reporting, and best practices, see [SECURITY.md](SECURITY.md).
## License
MIT
## Contributing
Contributions welcome! Please:
1. Review [SECURITY.md](SECURITY.md) for security guidelines
2. See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and workflow
3. Run `just check` before submitting PRs
4. Follow secure coding practices for any changes
Raw data
{
"_id": null,
"home_page": null,
"name": "kidshell",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "repl, shell, education, children, interactive, learning",
"author": "Anthony Wu",
"author_email": "Anthony Wu <ls-file-gh-issue@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/6f/c1ec2c50b37867276b07512693ad13c52c834f220e0bb08ee00be5a5bb3f/kidshell-0.1.0a0.tar.gz",
"platform": null,
"description": "# kidshell\n\n\n\nA [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) shell that is resilient in the face of _childish expectations_.\n\n> \ud83d\udd12 **Security First**: kidshell implements comprehensive security measures to protect young users.\n\nSee [SECURITY.md](SECURITY.md) for details on our security features and vulnerability reporting.\n\n## Quick Start\n\n```bash\n# Run without installation (recommended)\nuvx kidshell\n```\n\nOnce launched, think *\"What would a child do?\"* and try:\n\n- **Colors**: `blue`, `red`, `green` (or any color name)\n- **Emojis**: `bread`, `cat`, `star` (anything with an emoji)\n- **Ranges**: `0...100...1` or `0...10000...10...0.01`\n- **Math**: `1+1`, `pi`, `c`, `g`, `h`, `tau` (constants and expressions)\n- **Symbolic algebra**:\n - `x`, `x + 3`, `x = 2`, then `x + 3` again\n - Define multiple variables: `x + y - z`\n- **Just press Enter** - see what happens!\n- **Smash the keyboard** - it handles gibberish gracefully\n\n## Installation Options\n\n### For Parents and IT Admin\n\n```bash\n# Fastest - no installation needed\nuvx kidshell\n\n# Traditional pip install\npip install kidshell\n\n# Or any of these valid ways of installing kidshell as a reusable command\npipx install kidshell # global in PATH\nuv tool install kidshell # global in PATH\n\n# or into your preferred venv\npython -m venv OR uv venv\nsource .venv/bin/activate\nuv pip install kidshell # into an isolated venv\n```\n\n### For Developers\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for the complete development guide.\n\n**Quick start:**\n```bash\ngit clone https://github.com/anthonywu/kidshell.git\ncd kidshell\njust setup # Creates venv, installs deps\nsource .venv/bin/activate\njust run # Run kidshell\n```\n\n## Custom Data Configuration\n\nkidshell supports custom input\u2192output mappings stored in platform-specific directories:\n\n```bash\n# Edit custom data\nkidshell config # Opens editor with example.json\nkidshell config edit mydata.json # Create/edit specific file\nkidshell config list # List all data files\nkidshell config info # Show config locations\n```\n\nData files are JSON with custom mappings:\n\n```json\n{\n \"hello\": \"\ud83d\udc4b\",\n \"world\": \"\ud83c\udf0d\",\n \"cat\": \"\ud83d\udc31\",\n \"dog\": \"\ud83d\udc15\"\n}\n```\n\n## Project Structure\n\n```\nkidshell/\n\u251c\u2500\u2500 src/kidshell/ # Source code\n\u2502 \u251c\u2500\u2500 cli/ # CLI and REPL\n\u2502 \u251c\u2500\u2500 core/ # Core services\n\u2502 \u2514\u2500\u2500 frontends/ # UI frontends\n\u251c\u2500\u2500 tests/ # Test files\n\u251c\u2500\u2500 justfile # Development commands\n\u2514\u2500\u2500 pyproject.toml # Project configuration\n```\n\n## Roadmap\n\n1. \ud83d\udc65 Multiple profiles for N users in your family/classroom\n1. \ud83d\udda5 Run in browser or host at a web site\n1. \ud83d\udce5 Load user/family configs from public https URLs\n1. \ud83d\udcd6 Dictionary database/API integration for spelling validation\n1. \ud83d\udcac Translation lookups for multilingual households\n1. \ud83d\udd0a Text-to-speech integration via [localtalk](https://github.com/anthonywu/localtalk)\n1. \u2728 Local/offline AI magic, if applicable and reasonably to introduce to children.\n1. \ud83c\udfde Local/offline image generation with content moderation\n1. \ud83e\uddee Expand usage of math libraries\n1. \ud83c\udf10 More UI languages\n\n## Security\n\nkidshell takes security seriously, especially given our young user base. We implement:\n\n- **Path traversal protection** preventing unauthorized file system access\n- **Safe JSON processing** without code execution risks\n- **Subprocess security** with command validation and safe defaults\n- **Secure file operations** confined to user-specific directories\n\nFor detailed security information, vulnerability reporting, and best practices, see [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please:\n1. Review [SECURITY.md](SECURITY.md) for security guidelines\n2. See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and workflow\n3. Run `just check` before submitting PRs\n4. Follow secure coding practices for any changes\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A REPL shell that is resilient in the face of childish expectations",
"version": "0.1.0a0",
"project_urls": {
"Changelog": "https://github.com/anthonywu/kidshell/blob/main/CHANGELOG.md",
"Issues": "https://github.com/anthonywu/kidshell/issues",
"Repository": "https://github.com/anthonywu/kidshell"
},
"split_keywords": [
"repl",
" shell",
" education",
" children",
" interactive",
" learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f315beb0588c813d993144c4b7fbd3c07038caa54460735eb1eecbf212c624a4",
"md5": "9f1e5de16145e75ae2e722dc0119cfae",
"sha256": "b9f902d9bd9a845d2cd937be003962962b8e2e43da15ba75d3001852b739eb9b"
},
"downloads": -1,
"filename": "kidshell-0.1.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f1e5de16145e75ae2e722dc0119cfae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 52555,
"upload_time": "2025-08-08T02:26:28",
"upload_time_iso_8601": "2025-08-08T02:26:28.769316Z",
"url": "https://files.pythonhosted.org/packages/f3/15/beb0588c813d993144c4b7fbd3c07038caa54460735eb1eecbf212c624a4/kidshell-0.1.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb6fc1ec2c50b37867276b07512693ad13c52c834f220e0bb08ee00be5a5bb3f",
"md5": "de67ed307903d5dfc17fc1346b72d3e3",
"sha256": "d9b6fc75d5f021c3819f99cb323268d41adbfbcc1f02363679c3334086270e71"
},
"downloads": -1,
"filename": "kidshell-0.1.0a0.tar.gz",
"has_sig": false,
"md5_digest": "de67ed307903d5dfc17fc1346b72d3e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 40533,
"upload_time": "2025-08-08T02:26:29",
"upload_time_iso_8601": "2025-08-08T02:26:29.845886Z",
"url": "https://files.pythonhosted.org/packages/bb/6f/c1ec2c50b37867276b07512693ad13c52c834f220e0bb08ee00be5a5bb3f/kidshell-0.1.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 02:26:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anthonywu",
"github_project": "kidshell",
"github_not_found": true,
"lcname": "kidshell"
}
JSON
