kidshell

A REPL shell that is resilient in the face of childish expectations.

🔒 Security First: kidshell implements comprehensive security measures to protect young users.

See SECURITY.md for details on our security features and vulnerability reporting.

Quick Start

# 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

# 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 for the complete development guide.

Quick start:

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:

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

{
  "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
2. 🖥 Run in browser or host at a web site
3. 📥 Load user/family configs from public https URLs
4. 📖 Dictionary database/API integration for spelling validation
5. 💬 Translation lookups for multilingual households
6. 🔊 Text-to-speech integration via localtalk
7. ✨ Local/offline AI magic, if applicable and reasonably to introduce to children.
8. 🏞 Local/offline image generation with content moderation
9. 🧮 Expand usage of math libraries
10. 🌐 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.

License

MIT

Contributing

Contributions welcome! Please:

1. Review SECURITY.md for security guidelines
2. See DEVELOPMENT.md for development setup and workflow
3. Run just check before submitting PRs
4. Follow secure coding practices for any changes