[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1814":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":16,"starSnapshotCount":16,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},1814,"clawcodex","agentforce314\u002Fclawcodex","agentforce314","Claude Code full Python rebuild. AI Coding Agent in 180K LoC pure Python!","",null,"Python",379,38,16,4,0,119,202,357,94.77,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34],"agent","ai-agent","claude","claude-code","code","coding","deepseek","llm","python","2026-06-12 04:00:11","\u003Cdiv align=\"center\">\n\n**English** | [中文](docs\u002Fi18n\u002FREADME_ZH.md) | [Français](docs\u002Fi18n\u002FREADME_FR.md) | [Русский](docs\u002Fi18n\u002FREADME_RU.md) | [हिन्दी](docs\u002Fi18n\u002FREADME_HI.md) | [العربية](docs\u002Fi18n\u002FREADME_AR.md) | [Português](docs\u002Fi18n\u002FREADME_PT.md)\n\n# ClawCodex\n\n**A production-oriented Python rebuild of Claude Code — real architecture, reliable CLI agent**\n\n*Ported from the TypeScript reference implementation and extended with a Python-native runtime*\n\n***\n\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fagentforce314\u002Fclawcodex?style=for-the-badge&logo=github&color=yellow)](https:\u002F\u002Fgithub.com\u002Fagentforce314\u002Fclawcodex\u002Fstargazers)\n[![GitHub forks](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Fagentforce314\u002Fclawcodex?style=for-the-badge&logo=github&color=blue)](https:\u002F\u002Fgithub.com\u002Fagentforce314\u002Fclawcodex\u002Fnetwork\u002Fmembers)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg?style=for-the-badge)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Python 3.10+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n\n\n**🔥 Active Development • New Features Weekly 🔥**\n\n![ClawCodex Screenshot](assets\u002Fclawcodex-screenshot-1.png)\n\n\u003C\u002Fdiv>\n\n***\n\n## ⚡ Quick Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fagentforce314\u002Fclawcodex.git\ncd clawcodex\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate   # Python 3.10+\npip install -r requirements.txt\n\npython -m src.cli login   # writes config to ~\u002F.clawcodex\u002Fconfig.json\n\npython -m src.cli         # start the REPL\n```\n\n***\n\n## 📰 News\n\n- **2026-05-21:** **Codebase stats** — Total Python files: 890 files; Total Lines of Python Code: **183,768 lines** (up from 177,428 lines on 2026-05-16; net −4 files from the `src\u002Ftool_system\u002Fagent_loop.py` consolidation into `src\u002Fquery\u002Fquery.py`).\n- **2026-05-21:** **`\u002Fadvisor` token-efficient coding mode (#181–#193)** — pair a cheap worker (`haiku-4-5`, $1\u002F$5 per Mtok) with an expensive reviewer (`opus-4-7`, $5\u002F$25) consulted only at decision points; ~6× cheaper than opus-only on typical sessions. Explicit `\u003Cprovider>:\u003Cmodel>` syntax, cross-provider routing (e.g. `deepseek\u002Fdeepseek-v4-pro` worker + `claude-opus-4-7` advisor via litellm), and live worker\u002Fadvisor token + USD cost in the status bar.\n- **2026-05-16:** **Codebase stats** — Total Python files: 894 files; Total Lines of Python Code: **177,428 lines** (up from 167,034 lines on 2026-05-14; ~+10.4k lines in two days, mostly ESC-cancellation hardening + image-handling parity).\n- **2026-05-16:** **Image-handling parity (Tier C, #149\u002F#154\u002F#155\u002F#156)** — Read tool TS image pipeline (sniff, resize\u002Fcompress, base64 cap); `@image.png` mentions inline as real `ImageBlock`s instead of mojibake; cross-provider Anthropic `image`\u002F`document` → OpenAI `image_url`\u002F`file` translation; pre-API base64 size validation in `BaseProvider`.\n- **2026-05-16:** **Subagent + Bash reliability** — custom subagents now discovered from `.claude\u002Fagents\u002F` (#151); Bash `tool_result` distinguishes timeout from ESC-abort so the model can tell the two apart (#152); async-subagent `AbortController` isolation pinned by regression tests so a parent's ESC doesn't fire a sibling's abort listeners (#153); cancelled `tool_result` reliably surfaces `REJECT_MESSAGE` on the production path (#150).\n- **2026-05-15 to 2026-05-16:** **ESC cancellation hardening across providers (#144–#148)** — mid-stream cancellation closes the streaming HTTP response within ~50ms for every supported provider (Anthropic, OpenAI, GLM, Minimax, DeepSeek, OpenRouter); shared `StreamAbortGuard` helper extracted; LiteLLM worker-thread iteration fixes long-tail hangs on OpenAI-compat backends.\n- **2026-05-15:** **SWE-bench Verified result** — `clawcodex` resolves **291\u002F499 (58.2%)** vs `openclaude` **265\u002F499 (53.0%)** on Gemini 2.5 Pro under the standardized harness (see [`eval\u002F`](eval\u002F) for the comparison framework — cumulative batching, parallel `--predict-workers`, full stream-json trace capture).\n- **2026-05-15:** **Native Gemini provider** — `src\u002Fproviders\u002Fgemini_provider.py` via the `google-genai` SDK. Schema sanitization keeps OpenAI-style tool definitions compatible with Gemini's stricter `Schema` (`oneOf`\u002F`additionalProperties` stripped, polymorphic params coerced to `string`).\n- **2026-05-14:** **Codebase stats** — Total Python files: 837 files; Total Lines of Python Code: **167,034 lines**.\n- **2026-05-14:** **ESC cancellation latency fix (#130)** — pressing ESC now cancels in-flight Bash commands and streaming responses within ~50ms, on top of the diff color-bar full-width render fix (#129) and the bypass-permissions outside-paths fix (#128).\n- **2026-05-12:** **Bootstrap + architecture docs** — new architecture overview at [`docs\u002FARCHITECTURE.md`](docs\u002FARCHITECTURE.md); production bootstrap port (memoized `init()`, trust boundary, unified `launch_repl(args)`, `--bare` fast path, schema migration runner); main query loop and agent loop routed through `dispatch_full` with deferred tool loading.\n- **2026-05-11 (v0.5.0):** **ClawCodex v0.5.0 released** — rebrand to ClawCodex across user-visible UI; reactive state subsystem ported (signals, store, session context, cost tracker, 1h cache eligibility); API layer hardened (output-token cap, request-id injection, message-level cache breakpoints, Haiku fast path, watchdog + non-streaming fallback, retry-with-stream); agent loop foundation (typed terminal, media recovery, blocking-limit guards, token budget, stop hooks, model fallback, continuation nudge); refreshed README screenshot.\n- **2026-05-10:** **MCP subsystem landed** — full Model Context Protocol support with OAuth wiring, HTTPS, XSS hardening, and async I\u002FO; passed a multi-pass security review.\n- **2026-05-10:** **Performance pass** — startup profiler, prompt-cache plumbing with sticky latches, bitmap + async search indexing with score-bound pruning, cold-start latency reduction, streaming hardening.\n- **2026-05-10:** **CCR remote bridge (phases 0–5)** — Direct Connect via `cc:\u002F\u002F` and `cc+unix:\u002F\u002F`, Bridge v2 transport, Remote Session viewer, CCR upstream proxy.\n- **2026-05-10:** **Standalone REPL modules** — vim mode, transcript search, IME cursor, terminal hyperlinks, frame metrics, thinking widget, per-tool permission specialization, output-styles frontmatter; REPL transcript readability and ANSI diff backgrounds.\n- **2026-05-08:** **Hooks system** — snapshot-based executor with workspace-trust gate, expanded event\u002Fsource taxonomy, schema validation, environment injection.\n- **2026-05-08:** **Multi-agent coordination** — typed task state machine, JSONL transcript writer, agent task lifecycle, progress tracker, task-notification routing, `SendMessage` peer DMs, swarm primitives, background resume, coordinator mode + worker agents, permission forwarding bridge; full test suite green on `main`.\n- **2026-05-07:** **Auto-memory + concurrency** — ported the persistent auto-memory subsystem (user \u002F feedback \u002F project \u002F reference types); concurrency-orchestrator and tool-execution parity with the TypeScript reference; permission-system gaps closed.\n- **2026-05-06:** **Subagent parity** — fork-subagent path ported; subagent async lifecycle aligned with TypeScript reference.\n- **2026-05-05:** **Docs polish** — added Quick Install section under header; documented the config path written by `clawcodex login`.\n- **2026-04-30:** **Skills subsystem parity** — Skills (project + user, named args, tool limits) brought to parity with the TypeScript reference.\n- **2026-04-29:** **REPL spinner UX** — show elapsed time and token count in the REPL spinner row.\n- **2026-04-27:** **New demo** — Adopt Me-style pet game (React + Vite + Vitest), generated end-to-end by ClawCodex.\n- **2026-04-26:** **Reliability fix** — DeepSeek thinking-mode replay failures and noisy permission prompts resolved.\n- **2026-04-25:** **DeepSeek support** — direct DeepSeek provider (V4 Pro \u002F Flash via `api.deepseek.com`) plus OpenRouter route.\n- **2026-04-25:** **API validation fix** — `AskUserQuestion` options schema fixed for API validation.\n- **2026-04-23:** **Generated demos** — CRM, LinkedIn, and Minecraft demo apps (all generated by ClawCodex itself) and a Demos section in the README.\n- **2026-04-21:** **Permissions wiring** — `--dangerously-skip-permissions` wired through every entrypoint (REPL, TUI, `-p`).\n- **2026-04-20:** **Initial public release** — first commit with project source, docs, tests, and build config.\n\n***\n\n## 🎯 Why ClawCodex?\n\n**ClawCodex** is a **production-oriented Python rebuild of Claude Code**, ported from the **real TypeScript architecture** and shipped as a **working CLI agent**, not just a source dump.\n\n- **Real Agent Runtime** — tool-calling loop, streaming REPL, session history, and multi-turn execution\n- **High-Fidelity Port** — keeps the original Claude Code architecture while adapting it to idiomatic Python\n- **Built to Hack On** — readable Python codebase, rich tests, and markdown-driven skill extensibility\n- **Multi-LLM providers** — the biggest step forward vs. upstream: Claude Code is built around Claude-series models only; ClawCodex is dedicated to wiring in **all major LLM providers** so you can choose the most **flexible** and **cost-effective** stack for agentic coding\n\n**A real Claude Code-style terminal workflow in Python: stream replies, call tools, fetch context, and extend behavior with skills.**\n\n**🚀 Try it now! Fork it, modify it, make it yours! Pull requests welcome!**\n\n***\n\n## 🏆 SWE-bench Verified — `clawcodex` outperforms `openclaude` on the same model\n\n![SWE-bench Verified — clawcodex vs openclaude on Gemini 2.5 Pro](assets\u002Fswebench-verified-gemini.png)\n\nOn the full **SWE-bench Verified** split (499 instances, the public agent-coding leaderboard), both agents driven by **Gemini 2.5 Pro** under our standardized harness:\n\n| Agent | Resolved | Unresolved | Error |\n|---|---:|---:|---:|\n| **clawcodex** | **291 \u002F 499 (58.2%)** | 124 | 84 |\n| openclaude | 265 \u002F 499 (53.0%) | 144 | 90 |\n\n- ✅ **Both solved**: 241    🟢 **Only clawcodex**: 50    🔵 **Only openclaude**: 24    ❌ **Neither**: 184\n\nReproduce locally — see [`eval\u002FREADME.md`](eval\u002FREADME.md) for the full workflow (cumulative batching, `--predict-workers N`, `--capture-traces`).\n\n***\n\n## ⭐ Star History\n\n[View star history on star-history.com](https:\u002F\u002Fwww.star-history.com\u002F?repos=agentforce314%2Fclawcodex&type=date&legend=top-left)\n\n## ✨ Features\n\n### Streaming Agent Experience\n\n```text\n>>> \u002Fstream on\n>>> Explain tests\u002Ftest_agent_loop.py\n[streaming answer...]\n• Read (tests\u002Ftest_agent_loop.py) running...\n  ↳ lines 1-180\n>>> \u002Frender-last\n```\n\n- True API streaming for direct replies plus richer streaming during tool-driven agent loops\n- Built-in `\u002Fstream` toggle for live output and `\u002Frender-last` for clean Markdown re-rendering on demand\n- Designed for real terminal demos: streaming text, visible tool activity, and stable fallback behavior\n\n### Programmable Skill Runtime\n\n```md\n---\ndescription: Explain code with diagrams and analogies\nallowed-tools:\n  - Read\n  - Grep\n  - Glob\narguments: [path]\n---\n\nExplain the code in $path. Start with an analogy, then draw a diagram.\n```\n\n- Markdown-based `SKILL.md` slash commands\n- Supports project skills, user skills, named arguments, and tool limits\n\n### Multi-Provider Support\n\nClawCodex’s main advantage is **multi-provider support**: while Claude Code targets **Claude** models, we aim to support **every major LLM provider** behind the same agent runtime—so you can swap vendors, regions, and price tiers without giving up tools, skills, or the coding loop. That flexibility is what makes agentic coding practical at scale.\n\n```python\nproviders = [\"anthropic\", \"openai\", \"glm\", \"minimax\", \"openrouter\", \"deepseek\"]  # OpenAI-compatible & GLM APIs; more can be added\n```\n\n### Interactive REPL (default) and Textual TUI (opt-in)\n\nThe **default** interactive UI is the inline **prompt_toolkit + Rich** REPL (transcript in scrollback, tool-aware status row). Use **`clawcodex --tui`** or the **`\u002Ftui`** slash command inside the REPL to launch the **Textual** in-app experience when you want it.\n\n```text\n>>> Hello!\nAssistant: Hi! I'm ClawCodex, a Python reimplementation...\n\n>>> \u002Fhelp          # Show commands\n>>> \u002Ftools         # List registered tools\n>>> \u002Ftui           # Hand off to the Textual TUI\n>>> \u002Fstream on     # Live response rendering\n>>> \u002Fsave          # Save session\n>>> Tab            # Auto-complete\n>>> \u002Fexplain-code qsort.py   # Run a SKILL.md skill (or \u002Fskill …)\n\n# Multi-line input: Shift+Enter, Meta\u002FAlt+Enter, or `\\` then Enter for newline; plain Enter submits.\n```\n\n### Complete CLI\n\n```bash\nclawcodex                       # Inline REPL (default)\nclawcodex --tui                 # Textual TUI\nclawcodex --stream              # REPL with live rendering\nclawcodex login                 # Configure API keys (interactive)\nclawcodex config                # Show ~\u002F.clawcodex\u002Fconfig.json-backed settings\nclawcodex --version             # Version string\n\n# Non-interactive \u002F scripting (pipes, CI, agents)\nclawcodex -p \"Summarize src\u002Fcli.py\"\nclawcodex -p \"Hello\" --output-format json\nclawcodex -p --output-format stream-json --input-format stream-json \u003C events.ndjson\n\n# Overrides for a single run\nclawcodex --provider anthropic --model claude-sonnet-4-6 -p \"Hi\"\nclawcodex --max-turns 10 --allowed-tools Read,Grep -p \"Find TODOs\"\n\n# Permission control (REPL, TUI, and -p all honor these)\nclawcodex --permission-mode plan                       # plan \u002F acceptEdits \u002F dontAsk\nclawcodex --dangerously-skip-permissions -p \"ls\"       # bypass all permission checks\nclawcodex --allow-dangerously-skip-permissions         # allow \u002Fpermission-mode bypass later\n```\n\n> **`--dangerously-skip-permissions`** disables every tool permission check\n> for the session. Recommended only inside sandboxed containers\u002FVMs with no\n> internet access. The flag is refused when the process is running as\n> root\u002Fsudo unless `IS_SANDBOX=1` or `CLAUDE_CODE_BUBBLEWRAP=1` is set.\n\n***\n\n## 📊 Status\n\n| Component     | Status     | Count     |\n| ------------- | ---------- | --------- |\n| REPL Commands | ✅ Complete | Built-ins + `\u002Ftools`, `\u002Fstream`, `\u002Fcontext`, `\u002Fcompact`, skills, etc. |\n| Tool System   | ✅ Complete | 30+ tools |\n| Automated Tests | ✅ Present | Tools, agent loop, providers, parity, REPL, auth, and more |\n| Documentation | ✅ Complete | Guides, i18n READMEs, [FEATURE_LIST.md](FEATURE_LIST.md) |\n\n### Core Systems\n\n| System | Status | Description |\n|--------|--------|-------------|\n| CLI Entry | ✅ | `clawcodex`, `login`, `config`, `-p` \u002F `--print`, `--tui`, `--stream`, `--version` |\n| Interactive REPL | ✅ | Default inline REPL; optional Textual TUI; history, tab completion, multiline |\n| Multi-Provider | ✅ | Anthropic, OpenAI, Zhipu GLM, Minimax, OpenRouter, DeepSeek — including Anthropic→OpenAI image \u002F document block translation for vision-capable OpenAI-compat backends |\n| Session Persistence | ✅ | Save\u002Fload sessions locally |\n| Agent Loop | ✅ | Tool calling loop with streaming and headless mode |\n| Skill System | ✅ | SKILL.md-based slash-command skills with args + tool limits |\n| Cancellation \u002F Abort | ✅ | ESC closes in-flight Bash, Grep\u002FGlob, and streaming HTTP within ~50ms across every provider; subagents get isolated `AbortController`s; `Bash` `tool_result` distinguishes timeout from ESC-abort |\n| Image Handling | ✅ | TS-parity Read pipeline (magic-byte sniff, resize\u002Fcompress to API limits); `@image.png` @-mentions inline as `ImageBlock`; pre-API base64 size validation in `BaseProvider._prepare_messages`; binary @-mentions (PDF\u002Fzip\u002Fdocx\u002F...) routed to a Read-tool hint instead of mojibake |\n| Context Building | 🟡 | Workspace \u002F git \u002F `CLAUDE.md` injection; richer summaries and memory still evolving |\n| Permission System | 🟡 | Framework and checks; full integration still in progress |\n| MCP | 🟡 | MCP-oriented tools and wiring; full protocol\u002Fruntime polish ongoing |\n\n### Tool System (30+ Tools Implemented)\n\n| Category | Tools | Status |\n|----------|-------|--------|\n| File Operations | Read, Write, Edit, Glob, Grep | ✅ Complete |\n| System | Bash execution | ✅ Complete |\n| Web | WebFetch, WebSearch | ✅ Complete |\n| Interaction | AskUserQuestion, SendMessage | ✅ Complete |\n| Task Management | TodoWrite, TaskManager, TaskStop | ✅ Complete |\n| Agent Tools | Agent, Brief, Team | ✅ Complete |\n| Configuration | Config, PlanMode, Cron | ✅ Complete |\n| MCP | MCP tools and resources | 🟡 Tools wired; full client\u002Fruntime still evolving |\n| Others | LSP, Worktree, Skill, ToolSearch | ✅ Complete |\n\n### Roadmap Progress\n\n- ✅ **Phase 0**: Installable, runnable CLI\n- ✅ **Phase 1**: Core Claude Code MVP experience\n- ✅ **Phase 2**: Real tool calling loop\n- 🟡 **Phase 3**: Context depth, permission integration, `\u002Fresume`-class recovery (in progress)\n- 🟡 **Phase 4**: MCP runtime depth, plugins, extensibility (tools exist; platform work continues)\n- ⏳ **Phase 5**: Python-native differentiators\n\n**See [FEATURE_LIST.md](FEATURE_LIST.md) for detailed feature status and PR guidelines.**\n\n## 🚀 Quick Start\n\n### Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fagentforce314\u002Fclawcodex.git\ncd clawcodex\n\n# Create venv (uv recommended)\nuv venv --python 3.11\nsource .venv\u002Fbin\u002Factivate\n\n# Install package + entry point (recommended)\nuv pip install -e \".[dev]\"\n\n# Alternative: requirements only, then editable install\n# uv pip install -r requirements.txt && uv pip install -e .\n```\n\n### Configure\n\n#### Option 1: Interactive (Recommended)\n\n```bash\nclawcodex login\n# or: python -m src.cli login\n```\n\nThis flow will:\n\n1. ask you to choose a provider: anthropic \u002F openai \u002F glm \u002F minimax \u002F openrouter \u002F deepseek\n2. ask for that provider's API key\n3. optionally save a custom base URL\n4. optionally save a default model\n5. set the selected provider as default\n\nThe configuration file is saved in in `~\u002F.clawcodex\u002Fconfig.json`. Example structure:\n\n```json\n{\n  \"default_provider\": \"anthropic\",\n  \"providers\": {\n    \"anthropic\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fapi.anthropic.com\",\n      \"default_model\": \"claude-sonnet-4-6\"\n    },\n    \"openai\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fapi.openai.com\u002Fv1\",\n      \"default_model\": \"gpt-5.4\"\n    },\n    \"glm\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fopen.bigmodel.cn\u002Fapi\u002Fpaas\u002Fv4\",\n      \"default_model\": \"zai\u002Fglm-5\"\n    },\n    \"minimax\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fapi.minimaxi.com\u002Fanthropic\",\n      \"default_model\": \"MiniMax-M2.7\"\n    },\n    \"openrouter\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\",\n      \"default_model\": \"deepseek\u002Fdeepseek-v4-pro\"\n    },\n    \"deepseek\": {\n      \"api_key\": \"your-api-key\",\n      \"base_url\": \"https:\u002F\u002Fapi.deepseek.com\",\n      \"default_model\": \"deepseek-v4-pro\"\n    }\n  }\n}\n```\n\n### Run\n\n```bash\nclawcodex                  # Start inline REPL (same as python -m src.cli)\nclawcodex --help           # All flags: --tui, -p, --provider, --model, …\n```\n\n**That's it!** Configure keys, then run the CLI or REPL.\n\n***\n\n## 💡 Usage\n\n### REPL Commands\n\n| Command | Description |\n| -------- | ----------- |\n| `\u002F` | Show commands and skills |\n| `\u002Fhelp` | Help text |\n| `\u002Ftools` | List tool names from the registry |\n| `\u002Ftool \u003Cname> \u003Cjson>` | Run a tool directly with JSON input |\n| `\u002Fstream` | Toggle streaming: `\u002Fstream on`, `off`, or `toggle` |\n| `\u002Frender-last` | Re-render last assistant reply as Markdown |\n| `\u002Fsave` \u002F `\u002Fload \u003Cid>` | Persist or restore a session |\n| `\u002Fclear` | Clear conversation (also `\u002Freset`, `\u002Fnew`) |\n| `\u002Ftui` | Switch to the Textual TUI |\n| `\u002Fskill` | Skill launcher flow |\n| `\u002Fcontext` | Workspace \u002F prompt context (when available) |\n| `\u002Fcompact` | Compact or clear conversation (fallback clears if compact unavailable) |\n| `\u002Fexit`, `\u002Fquit`, `\u002Fq` | Exit |\n\n### Skills (Slash Commands)\n\nSkills are markdown-based slash commands stored under `.clawcodex\u002Fskills`. Each skill lives in its own directory and must be named `SKILL.md`.\n\n**1) Create a project skill**\n\nCreate:\n\n```text\n\u003Cproject-root>\u002F.clawcodex\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md\n```\n\nExample:\n\n```md\n---\ndescription: Explains code with diagrams and analogies\nwhen_to_use: Use when explaining how code works\nallowed-tools:\n  - Read\n  - Grep\n  - Glob\narguments: [path]\n---\n\nExplain the code in $path. Start with an analogy, then draw a diagram.\n```\n\n**2) Use it in the REPL**\n\n```text\n❯ \u002F\n❯ \u002F\u003Cskill-name> \u003Cargs>\n```\n\nExample:\n\n```text\n❯ \u002Fexplain-code qsort.py\n```\n\n**Notes**\n\n- User-level skills: `~\u002F.clawcodex\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`\n- Tool limits: `allowed-tools` controls which tools the skill can use.\n- Arguments: use `$ARGUMENTS`, `$0`, `$1`, or named args like `$path` (from `arguments`).\n- Placeholder syntax: use `$path`, not `${path}`.\n\n\n\n***\n\n## 🎨 Demos\n\n**Every app under [`demos\u002F`](demos\u002F) was generated end-to-end by ClawCodex itself** — same CLI you just installed, same agent loop, same tools. No hand-edits 🙂\n\n| Demo | Stack | Description |\n| ---- | ----- | ----------- |\n| [`demos\u002Fcrm-app`](demos\u002Fcrm-app) | React 18 + Vite + Vitest | Mini CRM with contacts, deals, dashboard, and a full test suite |\n| [`demos\u002Flinkedin-app`](demos\u002Flinkedin-app) | React 18 + Vite + React Router | LinkedIn-style feed: profile, network, jobs, messaging |\n| [`demos\u002Fminecraft-app`](demos\u002Fminecraft-app) | React + three.js + @react-three\u002Ffiber | Browser voxel sandbox with terrain, mining, HUD, and player controls |\n\n```bash\ncd demos\u002Fcrm-app   # or linkedin-app \u002F minecraft-app\nnpm install\nnpm run dev        # vite dev server\n```\n\nWant to see how it's done? Open ClawCodex in any empty directory and ask it to build something — these three were generated exactly that way.\n\n***\n\n## 🎓 Why ClawCodex?\n\n### Based on Real Source Code\n\n- **Not a clone** — Ported from actual TypeScript implementation\n- **Architectural fidelity** — Maintains proven design patterns\n- **Improvements** — Better error handling, more tests, cleaner code\n\n### Python Native\n\n- **Type hints** — Full type annotations\n- **Modern Python** — Uses 3.10+ features\n- **Idiomatic** — Clean, Pythonic code\n\n### User Focused\n\n- **3-step setup** — Clone, configure (`clawcodex login`), run (`clawcodex`)\n- **Interactive config** — Provider, base URL, and default model in one flow\n- **Inline or TUI** — Default terminal-native REPL; opt-in Textual UI\n- **Scriptable** — `-p` \u002F JSON \u002F NDJSON for automation\n- **Session persistence** — Save and reload conversations\n\n***\n\n## Architecture\n\nFor the six core abstractions (query loop, tools, tasks, two-tier state,\nmemory, hooks) and the golden path from user input to model output,\nsee [`docs\u002FARCHITECTURE.md`](docs\u002FARCHITECTURE.md). It is the recommended\nstarting point for new contributors.\n\nThe reference for the original Claude Code architecture is at\n`claude-code-from-source\u002Fbook\u002Fch01-architecture.md`; the\nchapter-by-chapter port gap analyses and refactoring plans live under\n`my-docs\u002F`.\n\n***\n\n\n## 📦 Project Structure\n\n```text\nclawcodex\u002F\n├── src\u002F\n│   ├── cli.py              # CLI entry (console: clawcodex)\n│   ├── entrypoints\u002F        # Headless (-p) and TUI bootstraps\n│   ├── repl\u002F               # Inline REPL (prompt_toolkit + Rich)\n│   ├── tui\u002F                # Textual UI (--tui, \u002Ftui)\n│   ├── providers\u002F          # Anthropic, OpenAI, GLM, Minimax, OpenRouter, DeepSeek\n│   ├── agent\u002F              # Conversation, session, prompts\n│   ├── tool_system\u002F        # Agent loop, tools, schemas\n│   ├── skills\u002F             # SKILL.md loading and skill tool\n│   ├── services\u002F           # MCP, compact, IDE bridge, tool execution, …\n│   ├── context_system\u002F     # Workspace \u002F git \u002F CLAUDE.md context\n│   ├── permissions\u002F        # Permission modes and bash parsing\n│   ├── hooks\u002F              # Hook types and execution helpers\n│   └── command_system\u002F     # Slash commands and substitution\n├── typescript\u002F             # Reference \u002F parity source (not required to run Python CLI)\n├── tests\u002F                  # pytest suites\n├── docs\u002F                   # Guides, i18n READMEs, refactor notes\n├── .clawcodex\u002Fskills\u002F      # Project-local skills (optional)\n├── FEATURE_LIST.md         # Capability matrix and roadmap\n└── pyproject.toml          # Package metadata and clawcodex script\n```\n\n***\n\n\n## 🤝 Contributing\n\n**We welcome contributions!**\n\n```bash\n# Quick dev setup\npip install -e .[dev]\npython -m pytest tests\u002F -v\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n***\n\n## 📖 Documentation\n\n- **[SETUP_GUIDE.md](docs\u002Fguide\u002FSETUP_GUIDE.md)** — Detailed installation\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Development guide\n- **[TESTING.md](docs\u002Fguide\u002FTESTING.md)** — Testing guide\n- **[CHANGELOG.md](CHANGELOG.md)** — Version history\n\n***\n\n## ⚡ Performance\n\n- **Startup**: \u003C 1 second\n- **Memory**: \u003C 50MB\n- **Response**: Turn-based assistant output with Rich markdown rendering\n\n***\n\n## 🔒 Security\n\n✅ **Basic Local Safety Practices**\n\n- No sensitive data in Git\n- API keys obfuscated in config\n- `.env` files ignored\n- Safe for local development workflows\n\n***\n\n## 📄 License\n\nMIT License — See [LICENSE](LICENSE)\n\n***\n\n## 🙏 Acknowledgments\n\n- Based on Claude Code TypeScript source\n- Independent educational project\n- Not affiliated with Anthropic\n\n***\n\n\u003Cdiv align=\"center\">\n\n### 🌟 Show Your Support\n\nIf you find this useful, please **star** ⭐ the repo!\n\n**Made with ❤️ by ClawCodex Team**\n\n[⬆ Back to Top](#clawcodex)\n\n\u003C\u002Fdiv>\n\n***\n\n***","ClawCodex 是一个完全用 Python 重写的 Claude Code 项目，旨在提供一个生产级的 AI 编码代理。该项目拥有约18万行纯 Python 代码，支持可靠的命令行界面（CLI）代理功能，并从 TypeScript 版本移植而来，同时扩展了 Python 原生运行时环境。核心功能包括高效的编码辅助、多模型协作以及图像处理能力，特别是通过低成本工作器与高成本审查者的搭配使用来优化成本效益。适用于需要自动化代码生成、改进或分析的开发场景，尤其是在追求跨平台兼容性和资源效率的情况下。",2,"2026-06-11 02:46:12","CREATED_QUERY"]