{"id":"19ff11a1-9bcb-4f87-a181-a2d3a2a6852c","slug":"code-flash","kind":"mcp","name":"code-flash","summary":"","owner":"ttchu1221","repoUrl":"https://github.com/ttchu1221/code-flash","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-27T05:22:29.000Z","addedAt":"2026-10-21T21:14:06.130Z","logoUrl":"https://avatars.githubusercontent.com/u/79637676?u=6eacc4979cb0d37b4b19151043637f7b30f054e2&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T23:40:08.513Z","sample":false,"url":"https://conduits.dev/tools/code-flash","language":"Python","transports":["stdio"],"install":{"pypi":"code-flash"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n# ⚡ Code Flash\n\n**Ultra-light AI Agent Scaffolding**\n\n**Agentic** &nbsp;·&nbsp; **Built to Extend** &nbsp;·&nbsp; **~1000 Lines of Python Core**\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n</div>\n\n---\n\nCode Flash is a minimal, hackable AI coding assistant framework. It provides a complete agentic loop with tool execution, permission management, session persistence, and a beautiful terminal UI — all in ~1000 lines of Python.\n\nInspired by [Claude Code](https://docs.anthropic.com/en/docs/claude-code), based on [cc-mini](https://github.com/nicobailon/cc-mini), extended with features like **Coordinator Mode**, **Buddy (AI Companion Pet)**, **KAIROS Memory**, **Skills System**, and **Sandbox Isolation**.\n\n## ✨ Features\n\n### Core\n\n- **Interactive REPL** with streaming output, command history, slash command autocomplete\n- **Agentic tool loop** — LLM calls tools autonomously until the task is complete\n- **9 built-in tools**: `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Bash`, `AskUser`, `EnterPlanMode`, `ExitPlanMode`\n- **Plan mode** — parallel subagents explore codebase before you implement\n- **Permission system** — mode-aware (default/plan), reads auto-approved, writes ask for confirmation\n- **Session persistence** — auto-save conversations, `/resume` to continue later\n- **Context compression** — auto-compact when approaching token limits\n- **Anthropic + OpenAI compatible** — works with any compatible API endpoint\n\n### Advanced\n\n| Feature | Description | Docs |\n|---------|-------------|------|\n| **Coordinator Mode** | Background workers for parallel research and implementation | [docs →](docs/coordinator.md) |\n| **Buddy** | Tamagotchi AI pet with personality, stats, mood, and speech bubbles | [docs →](docs/buddy.md) |\n| **KAIROS Memory** | Cross-session memory with auto-consolidation | [docs →](docs/memory.md) |\n| **Skills** | One-command workflows: `/review`, `/commit`, `/test`, `/simplify` | [docs →](docs/skills.md) |\n| **Sandbox** | Bubblewrap isolation for bash commands (Linux) | [docs →](docs/sandbox.md) |\n| **MCP** | Model Context Protocol — connect external tool servers | [see below](#-mcp-model-context-protocol) |\n\n### Web UI\n\nA full-featured web interface with real-time streaming, file explorer, and settings panel.\n\n```bash\ncd web && ./start.sh    # Production mode\ncd web && ./dev.sh      # Dev mode with hot reload\n```\n\nSee [web/README.md](web/README.md) for details.\n\n---\n\n## 🚀 Quick Start\n\n### Requirements\n\n- Python 3.11+ (3.12 recommended)\n- An API key for [Anthropic](https://console.anthropic.com/) or any OpenAI-compatible provider\n\n### Install\n\n```bash\n# One-line install (recommended)\ncurl -fsSL https://raw.githubusercontent.com/ttchu1221/code-flash/main/install.sh | bash\n\n# Or manual\ngit clone https://github.com/ttchu1221/code-flash.git\ncd code-flash\npip install -e \".[dev]\"\n```\n\n### Set API Key\n\n```bash\n# Anthropic\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n# Or OpenAI-compatible\nexport CODE_FLASH_PROVIDER=openai\nexport OPENAI_API_KEY=sk-...\nexport OPENAI_BASE_URL=https://your-gateway.example.com/v1\nexport CODE_FLASH_MODEL=gpt-...\n```\n\n### Run\n\n```bash\ncode-flash                              # Interactive REPL\ncode-flash \"what tests exist?\"          # One-shot prompt\ncode-flash -p \"summarize this codebase\" # Print and exit\ncode-flash --auto-approve               # Skip permission prompts\ncode-flash --resume 1                   # Resume previous session\ncode-flash --coordinator                # Coordinator mode\n```\n\n---\n\n## 🛠 Tools\n\n| Tool | Description | Permission |\n|------|-------------|------------|\n| `Read` | Read file contents | auto-approved |\n| `Glob` | Find files by pattern | auto-approved |\n| `Grep` | Search file contents | auto-approved |\n| `Edit` | Edit file (string replacement) | requires confirmation |\n| `Write` | Write/create file | requires confirmation |\n| `Bash` | Run shell command | requires confirmation |\n| `AskUser` | Ask user a question | auto-approved |\n| `EnterPlanMode` | Enter plan mode | auto-approved |\n| `ExitPlanMode` | Exit plan mode | auto-approved |\n\nCoordinator mode adds: `Agent` (spawn worker), `SendMessage` (continue worker), `TaskStop` (stop worker).\n\n---\n\n## 🔌 MCP (Model Context Protocol)\n\nCode Flash supports the [Model Context Protocol](https://modelcontextprotocol.io/) — connect external tool servers to extend the agent's capabilities with filesystem access, databases, APIs, and more.\n\n### Install MCP SDK\n\n```bash\npip install -e \".[mcp]\"\n```\n\n### Configuration\n\nCreate a `mcp.json` in your project root (or `~/.config/code-flash/mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"]\n    },\n    \"remote-api\": {\n      \"url\": \"http://localhost:8080/sse\"\n    }\n  }\n}\n```\n\nOr use `config.toml`:\n\n```toml\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"]\n\n[mcp_servers.remote-api]\nurl = \"http://localhost:8080/sse\"\n```\n\n### Commands\n\n- `/mcp` — Show connected servers and available tools\n- `/mcp reconnect` — Reconnect to all MCP servers\n\n---\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `CODE_FLASH_MODEL` | Model name (e.g. `claude-sonnet-4-5`) |\n| `CODE_FLASH_MAX_TOKENS` | Max output tokens |\n| `CODE_FLASH_EFFORT` | Reasoning effort (`low`, `medium`, `high`) |\n| `CODE_FLASH_PROVIDER` | `anthropic` or `openai` |\n| `CODE_FLASH_BUDDY_MODEL` | Model for companion pet reactions |\n| `CODE_FLASH_BUDDY_SEED` | Override buddy seed for specific companion |\n\n### TOML Config Files\n\nLoaded in order (later overrides earlier):\n\n1. `~/.config/code-flash/config.toml`\n2. `.code-flash.toml` in the current working directory\n\n```toml\n# Example: .code-flash.toml\n[anthropic]\napi_key = \"sk-ant-...\"\nmodel = \"claude-sonnet-4\"\n\n[sandbox]\nenabled = true\nauto_allow_bash = true\n```\n\nSee [docs/configuration.md](docs/configuration.md) for full details.\n\n---\n\n## 📁 Data Paths\n\n| Data | Path |\n|------|------|\n| Installation (source code) | `~/.code-flash/` |\n| Sessions | `~/.config/code-flash/sessions/` |\n| Memory (KAIROS) | `~/.config/code-flash/memory/` |\n| Plans | `~/.config/code-flash/plans/` |\n| REPL history | `~/.config/code-flash/history` |\n| Companion data | `~/.config/code-flash/companion.json` |\n| User skills | `~/.config/code-flash/skills/` |\n| Project skills | `{cwd}/.code-flash/skills/` |\n| Project config | `.code-flash.toml` |\n\n---\n\n## 💬 Slash Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show all available commands |\n| `/compact` | Compress conversation context |\n| `/resume` | Resume a past session |\n| `/history` | List saved sessions |\n| `/clear` | Clear conversation, start new session |\n| `/skills` | List all available skills |\n| `/buddy` | Companion pet — hatch, pet, stats, mood |\n| `/review` | Code review (skill) |\n| `/commit` | Git commit (skill) |\n| `/test` | Run tests (skill) |\n| `/simplify` | Review and fix code (skill) |\n| `/plan` | Enter plan mode |\n| `/model` | Switch model |\n| `/mcp` | Show MCP server status and tools |\n| `/advisor` | Toggle advisor mode |\n\nType `/` to see autocomplete suggestions.\n\n---\n\n## 🏗 Project Structure\n\n```\nsrc/\n├── core/                  # Pure harness — engine, LLM, config\n│   ├── engine.py          # Streaming API loop + tool execution\n│   ├── llm.py             # LLM client (Anthropic + OpenAI)\n│   ├── config.py          # Configuration (CLI, env, TOML, MCP)\n│   ├── context.py         # System prompt builder\n│   ├── tool.py            # Base Tool protocol + ToolResult\n│   ├── permissions.py     # Permission checker\n│   ├── session.py         # Session persistence\n│   ├── mcp_client.py      # MCP client manager (stdio/SSE)\n│   └── mcp_tool.py        # MCP tool wrapper → Tool interface\n│\n├── tools/                 # Tool implementations (one per file)\n│   ├── bash.py            # Shell command execution\n│   ├── file_read.py       # Read files\n│   ├── file_edit.py       # Edit files (string replacement)\n│   ├── file_write.py      # Write/create files\n│   ├── glob_tool.py       # Find files by pattern\n│   ├── grep_tool.py       # Search file contents\n│   ├── ask_user.py        # Ask user questions\n│   ├── plan_tools.py      # EnterPlanMode / ExitPlanMode\n│   └── agent.py           # Coordinator agent tools\n│\n├── features/              # Pluggable capabilities\n│   ├── compact.py         # Context compression\n│   ├── coordinator.py     # Coordinator mode\n│   ├── cost_tracker.py    # Token usage tracking\n│   ├── memory.py          # KAIROS memory system\n│   ├── plan.py            # Plan mode logic\n│   ├── skills.py          # Skill loader and registry\n│   ├── skills_bundled.py  # Built-in skills\n│   └── sandbox/           # Bubblewrap sandbox subsystem\n│\n├── tui/                   # Terminal UI\n│   ├── app.py             # CLI entry point + REPL\n│   ├── query.py           # Query submission + streaming display\n│   ├── rendering.py       # Rich console rendering\n│   └── prompt.py          # Input prompt\n│\n├── commands/              # Slash command handlers\n├── buddy/                 # AI companion pet system\n│   ├── companion.py       # Deterministic companion generation\n│   ├── mood.py            # Mood engine\n│   ├── sprites.py         # ASCII sprite art\n│   └── poke_game/         # Idle adventure game\n│\nweb/                       # Web UI\n├── backend/               # FastAPI + WebSocket\n└── frontend/              # React + TypeScript + Tailwind\n```\n\n---\n\n## 🧪 Running Tests\n\n```bash\npytest tests/ -v\npytest tests/ -v -k \"not integration\"  # skip bwrap tests\n```\n\n---\n\n## 📚 Documentation\n\n| Topic | Link |\n|-------|------|\n| Configuration | [docs/configuration.md](docs/configuration.md) |\n| Buddy (AI Companion) | [docs/buddy.md](docs/buddy.md) |\n| Coordinator Mode | [docs/coordinator.md](docs/coordinator.md) |\n| KAIROS Memory System | [docs/memory.md](docs/memory.md) |\n| Skills | [docs/skills.md](docs/skills.md) |\n| Sandbox | [docs/sandbox.md](docs/sandbox.md) |\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests (`pytest tests/ -v`)\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## 📄 License\n\nThis project is open source and available under the [MIT License](LICENSE).\n"}