Remove obsolete project docs
This commit is contained in:
武阳
@@ -1,843 +0,0 @@
|
|||||||
# Parity Checklist Against npm `src`
|
|
||||||
|
|
||||||
This document tracks what is already implemented in Python and what is still missing compared with the upstream npm runtime.
|
|
||||||
|
|
||||||
This is a functionality-oriented checklist, not a line-by-line source equivalence claim. Large parts of the mirrored Python workspace still act as inventory or scaffolding, while the working Python runtime currently lives mainly in [`src/agent_runtime.py`](src/agent_runtime.py), [`src/query_engine.py`](src/query_engine.py), [`src/agent_tools.py`](src/agent_tools.py), [`src/agent_prompting.py`](src/agent_prompting.py), [`src/agent_context.py`](src/agent_context.py), [`src/agent_manager.py`](src/agent_manager.py), [`src/plugin_runtime.py`](src/plugin_runtime.py), [`src/agent_slash_commands.py`](src/agent_slash_commands.py), [`src/openai_compat.py`](src/openai_compat.py), [`src/builtin_agents.py`](src/builtin_agents.py), [`src/microcompact.py`](src/microcompact.py), [`src/compact.py`](src/compact.py), [`src/bundled_skills.py`](src/bundled_skills.py), and [`src/session_memory_compact.py`](src/session_memory_compact.py).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Core Agent Runtime
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] One-shot agent loop with iterative tool calling
|
|
||||||
- [x] OpenAI-compatible `chat/completions` client
|
|
||||||
- [x] Streaming token-by-token assistant output
|
|
||||||
- [x] Local-model execution against `vLLM`
|
|
||||||
- [x] Local-model execution through `Ollama`
|
|
||||||
- [x] Local-model execution through `LiteLLM Proxy`
|
|
||||||
- [x] Transcript-aware session object for the Python runtime
|
|
||||||
- [x] Session save and resume support
|
|
||||||
- [x] Configurable max-turn execution
|
|
||||||
- [x] Permission-aware tool execution
|
|
||||||
- [x] Structured output / JSON schema request mode
|
|
||||||
- [x] Cost tracking and usage budget enforcement
|
|
||||||
- [x] Scratchpad directory integration
|
|
||||||
- [x] File history journaling for write/edit/shell tool actions
|
|
||||||
- [x] Incremental `bash` tool-result streaming events
|
|
||||||
- [x] Incremental tool-result streaming for read-only text tools
|
|
||||||
- [x] Incremental tool-result streaming across the current Python text tool surface
|
|
||||||
- [x] Mutable tool transcript updates during tool execution
|
|
||||||
- [x] Transcript mutation history for replaced/tombstoned messages
|
|
||||||
- [x] Assistant streaming and tool-call transcript mutation history
|
|
||||||
- [x] Session-wide mutation serial tracking across transcript updates
|
|
||||||
- [x] Structured transcript block export for messages, tool calls, and tool results
|
|
||||||
- [x] Resume-time file-history replay reminders
|
|
||||||
- [x] Resume-time file-history snapshot previews for file edits
|
|
||||||
- [x] File-history snapshot ids and replay summaries for file edits
|
|
||||||
- [x] File-history result previews for shell and delegated-tool entries
|
|
||||||
- [x] Truncated-response continuation flow for `finish_reason=length`
|
|
||||||
- [x] Basic snipping of older tool/tool-call messages for context control
|
|
||||||
- [x] Basic automatic compact-boundary insertion with preserved recent tail
|
|
||||||
- [x] Reactive compaction retry after prompt-too-long backend failures
|
|
||||||
- [x] Reasoning-token budget enforcement
|
|
||||||
- [x] Tool-call and delegated-task budget enforcement
|
|
||||||
- [x] Resume-aware cumulative model-call budgets
|
|
||||||
- [x] Resume-aware cumulative session usage/cost persistence
|
|
||||||
- [x] Basic nested-agent delegation tool
|
|
||||||
- [x] Sequential multi-subtask delegation with parent-context carryover
|
|
||||||
- [x] Dependency-aware delegated subtasks
|
|
||||||
- [x] Topological dependency-batch delegation planning
|
|
||||||
- [x] Basic agent-manager lineage tracking for nested agents
|
|
||||||
- [x] Managed agent-group membership tracking with child indices
|
|
||||||
- [x] Agent-manager strategy and batch summary tracking for delegated groups
|
|
||||||
- [x] Delegated child-session resume by saved session id
|
|
||||||
- [x] Agent-manager tracking for resumed child-session lineage
|
|
||||||
- [x] Plugin-cache discovery and prompt-context injection
|
|
||||||
- [x] Manifest-based plugin runtime discovery
|
|
||||||
- [x] Manifest-defined plugin hooks for before-prompt and after-turn runtime injection
|
|
||||||
- [x] Manifest-defined plugin lifecycle hooks for resume, persist, and delegate phases
|
|
||||||
- [x] Manifest-defined plugin tool aliases over base runtime tools
|
|
||||||
- [x] Manifest-defined executable virtual tools
|
|
||||||
- [x] Manifest-defined plugin tool blocking
|
|
||||||
- [x] Manifest-defined plugin `beforeTool` guidance
|
|
||||||
- [x] Manifest-defined plugin tool-result guidance injected back into the transcript
|
|
||||||
- [x] Plugin runtime session-state persistence and resume restoration
|
|
||||||
- [x] Manifest-based hook/policy runtime discovery
|
|
||||||
- [x] Hook/policy before-prompt runtime injection
|
|
||||||
- [x] Hook/policy after-turn runtime events
|
|
||||||
- [x] Hook/policy tool preflight guidance
|
|
||||||
- [x] Hook/policy tool blocking
|
|
||||||
- [x] Hook/policy after-tool guidance
|
|
||||||
- [x] Hook/policy budget override loading
|
|
||||||
- [x] Hook/policy safe-environment overlay for shell tools
|
|
||||||
- [x] Local manifest-backed MCP resource discovery
|
|
||||||
- [x] Local MCP resource listing and reading
|
|
||||||
- [x] MCP-backed runtime tools for local resource access
|
|
||||||
- [x] Real stdio MCP client transport for `initialize`, `resources/list`, `resources/read`, `tools/list`, and `tools/call`
|
|
||||||
- [x] Transport-backed MCP tool listing and execution
|
|
||||||
- [x] Local manifest-backed remote runtime discovery
|
|
||||||
- [x] Local remote profile listing and summary reporting
|
|
||||||
- [x] Local remote connect/disconnect state persistence
|
|
||||||
- [x] Local manifest/env-backed search runtime discovery
|
|
||||||
- [x] Local search-provider activation persistence
|
|
||||||
- [x] Provider-backed web search execution against configured search backends
|
|
||||||
- [x] Local heuristic LSP runtime for definitions, references, hover, document symbols, workspace symbols, call hierarchy, and diagnostics
|
|
||||||
- [x] Local persistent task runtime discovery
|
|
||||||
- [x] Local task create/get/list/update runtime flows
|
|
||||||
- [x] Local todo-list replacement runtime flow
|
|
||||||
- [x] Local persistent plan runtime discovery
|
|
||||||
- [x] Local plan get/update/clear runtime flows
|
|
||||||
- [x] Local plan-to-task sync flow
|
|
||||||
- [x] Dependency-aware local task state with blocking and actionable-task selection
|
|
||||||
- [x] Local task start/complete/block/cancel execution flows
|
|
||||||
- [x] Compaction metadata with compacted message ids
|
|
||||||
- [x] Compaction metadata with preserved-tail ids and compaction depth
|
|
||||||
- [x] Compaction metadata with compacted/preserved lineage ids and revision summaries
|
|
||||||
- [x] Compaction metadata with source mutation serials and mutation totals
|
|
||||||
- [x] Snipped-message metadata with source role/kind lineage
|
|
||||||
- [x] Snipped-message metadata with source lineage id and revision
|
|
||||||
- [x] Resume-time compaction / snipping replay reminder
|
|
||||||
- [x] Resume-time compaction replay of source mutation summaries
|
|
||||||
- [x] Preflight prompt-length validation before each model call
|
|
||||||
- [x] Hard prompt-length stop before backend calls when the effective input budget is exceeded
|
|
||||||
- [x] Token-budget calculation with projected prompt size, chat framing overhead, output reserve, and soft/hard input limits
|
|
||||||
- [x] Preflight auto-compact/context collapse fallback before the next model call
|
|
||||||
- [x] Query-engine facade that can drive the real Python runtime agent
|
|
||||||
- [x] Query-engine runtime event counters and transcript-kind summaries
|
|
||||||
- [x] Query-engine runtime mutation counters
|
|
||||||
- [x] Query-engine stream-level runtime summary event
|
|
||||||
- [x] Query-engine transcript-store compaction summaries
|
|
||||||
- [x] Delegate-group and delegated-subtask runtime events
|
|
||||||
- [x] Delegate-batch runtime events and summaries
|
|
||||||
- [x] Query-engine runtime orchestration summaries for group status and child stop reasons
|
|
||||||
- [x] Query-engine runtime context-reduction summaries
|
|
||||||
- [x] Query-engine runtime lineage summaries
|
|
||||||
- [x] Query-engine runtime resumed-child orchestration summaries
|
|
||||||
- [x] Filesystem-backed custom agent discovery from `~/.claude/agents` and `./.claude/agents`
|
|
||||||
- [x] Active agent override precedence across built-in, user, and project agent definitions
|
|
||||||
- [x] Custom agent resolution in the `Agent` tool with model, tool-filter, and initial-prompt support
|
|
||||||
- [x] Local custom-agent file creation, update, and deletion flows for project/user agent definitions
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full partial tool-result streaming parity across the complete upstream/npm tool surface
|
|
||||||
- [ ] Full rich transcript mutation behavior like the npm runtime beyond the current lineage, counters, block export, and mutation-serial tracking
|
|
||||||
- [ ] Full reasoning budgets and task budgets parity beyond the current cumulative model/tool/delegation/session-call enforcement
|
|
||||||
- [ ] Full multi-agent orchestration parity beyond dependency-aware batched delegation, resumed-child flows, and current agent-manager summaries
|
|
||||||
- [ ] Full file history snapshots and replay flows beyond the current preview/id-based implementation and delegated-batch replay metadata
|
|
||||||
- [ ] Full executable plugin lifecycle beyond manifest-driven prompt/tool/session hooks, blocking, aliases, virtual tools, and persisted runtime state
|
|
||||||
- [ ] Full session compaction / snipping parity beyond lineage-aware summaries, mutation-serial compaction metadata, and replay reminders
|
|
||||||
- [ ] Full `QueryEngine.ts` parity (session init, message normalization, SDK-compatible message transforms, attachment handling)
|
|
||||||
- [x] Auto-compact and context collapse features from `query.ts`
|
|
||||||
- [x] Prompt length validation from `query.ts`
|
|
||||||
- [x] Token budget calculations from `query/tokenBudget.ts`
|
|
||||||
|
|
||||||
## 2. CLI Entrypoints And Runtime Modes
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Python CLI entrypoint
|
|
||||||
- [x] `agent` command
|
|
||||||
- [x] `agent-chat` command
|
|
||||||
- [x] `agent-resume` command
|
|
||||||
- [x] `agent-prompt` command
|
|
||||||
- [x] `agent-context` command
|
|
||||||
- [x] `agent-context-raw` command
|
|
||||||
- [x] `token-budget` command
|
|
||||||
- [x] `agents` command
|
|
||||||
- [x] `agents-create` command
|
|
||||||
- [x] `agents-update` command
|
|
||||||
- [x] `agents-delete` command
|
|
||||||
- [x] Local background session mode
|
|
||||||
- [x] Local background session listing (`agent-ps`)
|
|
||||||
- [x] Local background session logs (`agent-logs`)
|
|
||||||
- [x] Local background attach snapshot (`agent-attach`)
|
|
||||||
- [x] Local background kill flow (`agent-kill`)
|
|
||||||
- [x] Local daemon-style background command family (`daemon start/ps/logs/attach/kill`)
|
|
||||||
- [x] Local daemon worker command path (`daemon worker`)
|
|
||||||
- [x] Local remote runtime CLI modes (`remote-mode`, `ssh-mode`, `teleport-mode`, `direct-connect-mode`, `deep-link-mode`)
|
|
||||||
- [x] Local remote runtime inspection commands (`remote-status`, `remote-profiles`, `remote-disconnect`)
|
|
||||||
- [x] Local account runtime inspection commands (`account-status`, `account-profiles`, `account-login`, `account-logout`)
|
|
||||||
- [x] Local search runtime inspection commands (`search-status`, `search-providers`, `search-activate`, `search`)
|
|
||||||
- [x] Local LSP runtime inspection commands (`lsp-status`, `lsp-symbols`, `lsp-workspace-symbols`, `lsp-definition`, `lsp-references`, `lsp-hover`, `lsp-diagnostics`, `lsp-call-hierarchy`, `lsp-incoming-calls`, `lsp-outgoing-calls`)
|
|
||||||
- [x] Local MCP runtime inspection commands (`mcp-status`, `mcp-resources`, `mcp-resource`, `mcp-tools`, `mcp-call-tool`)
|
|
||||||
- [x] Inventory/helper commands such as `summary`, `manifest`, `commands`, and `tools`
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full daemon supervisor parity beyond the current local daemon wrapper and worker flow
|
|
||||||
- [ ] Remote-control / bridge runtime mode (`src/bridge/` — 30+ files: bridgeMain, bridgeApi, bridgeConfig, bridgeMessaging, bridgePermissionCallbacks, replBridge, sessionRunner, trustedDevice, etc.)
|
|
||||||
- [ ] Browser/native-host runtime mode
|
|
||||||
- [ ] Computer-use MCP mode (`src/entrypoints/mcp.ts`)
|
|
||||||
- [ ] Template job mode
|
|
||||||
- [ ] Environment runner mode
|
|
||||||
- [ ] Self-hosted runner mode
|
|
||||||
- [ ] tmux fast paths
|
|
||||||
- [ ] Worktree fast paths at the CLI entrypoint level
|
|
||||||
- [x] Python (Node.js equivalent) version check and platform detection from `setup.ts`
|
|
||||||
- [ ] Worktree creation/setup from `setup.ts`
|
|
||||||
- [ ] Terminal backup/restore from `setup.ts`
|
|
||||||
- [x] Release notes checking from `setup.ts` (local CHANGELOG.md, no network/cache layer)
|
|
||||||
- [ ] Full `entrypoints/cli.tsx` parity (version flag, feature flags, env setup, dynamic imports)
|
|
||||||
- [ ] Full `entrypoints/init.ts` parity (settings validation, OAuth, policy limits, telemetry, cleanup handlers)
|
|
||||||
- [ ] SDK entrypoint (`entrypoints/sdk/` — controlTypes, coreTypes, runtimeTypes, settingsTypes, toolTypes) — partial: HOOK_EVENTS, EXIT_REASONS, ModelUsage, ThinkingConfig, MCP server configs, JsonSchemaOutputFormat ported in `src/sdk_core_types.py`
|
|
||||||
- [x] Sandbox types/network config schema (`entrypoints/sandboxTypes.ts`)
|
|
||||||
|
|
||||||
## 3. Prompt Assembly
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Structured Python system prompt builder
|
|
||||||
- [x] Intro/system/task/tool/tone/output sections
|
|
||||||
- [x] Session-specific prompt guidance
|
|
||||||
- [x] Environment-aware prompt sections
|
|
||||||
- [x] User context reminder injection
|
|
||||||
- [x] Custom system prompt override and append support
|
|
||||||
- [x] Local hook/policy guidance section in the Python system prompt
|
|
||||||
- [x] Local MCP guidance section in the Python system prompt
|
|
||||||
- [x] MCP transport/tool guidance section in the Python system prompt
|
|
||||||
- [x] Local remote-runtime guidance section in the Python system prompt
|
|
||||||
- [x] Local search-runtime guidance section in the Python system prompt
|
|
||||||
- [x] Local account-runtime guidance section in the Python system prompt
|
|
||||||
- [x] Local planning guidance section in the Python system prompt
|
|
||||||
- [x] Local task guidance section in the Python system prompt
|
|
||||||
- [x] Local LSP guidance section in the Python system prompt
|
|
||||||
- [x] Local agent-configuration guidance section in the Python system prompt
|
|
||||||
|
|
||||||
- [x] Product metadata/branding from `constants/product.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] API limits constants from `constants/apiLimits.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Tool limits constants from `constants/toolLimits.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Spinner verbs from `constants/spinnerVerbs.ts` (187 verbs) — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Turn-completion verbs from `constants/turnCompletionVerbs.ts` (8 verbs) — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Figures/UI symbols from `constants/figures.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] XML tag constants from `constants/xml.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Message constants from `constants/messages.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Date utilities from `constants/common.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] System prompt section caching from `constants/systemPromptSections.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Output-style variants from `constants/outputStyles.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Cyber / risk instruction from `constants/cyberRiskInstruction.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] System prompt prefixes from `constants/system.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Knowledge cutoff / model family info from `constants/prompts.ts` — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Hook instruction section template — ported to `src/prompt_constants.py`
|
|
||||||
- [x] System reminders section — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Summarize tool results section — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Language-control section helper — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Scratchpad prompt instructions helper — ported to `src/prompt_constants.py`
|
|
||||||
- [x] Default agent prompt — ported to `src/prompt_constants.py`
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full parity with `constants/prompts.ts` runtime section assembly (many sections already exist in agent_prompting.py)
|
|
||||||
- [ ] MCP instruction sections (runtime MCP integration)
|
|
||||||
- [ ] Model-family-specific prompt variations (runtime)
|
|
||||||
- [ ] More exact autonomous/proactive behavior sections
|
|
||||||
- [ ] Growthbook / feature-gated prompt sections (N/A for external builds)
|
|
||||||
|
|
||||||
## 4. Context Building And Memory
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Current working directory snapshot
|
|
||||||
- [x] Shell / platform / date capture
|
|
||||||
- [x] Git status snapshot
|
|
||||||
- [x] `CLAUDE.md` discovery
|
|
||||||
- [x] Extra directory injection through `--add-dir`
|
|
||||||
- [x] Session context usage report
|
|
||||||
- [x] Tokenizer-aware context accounting with cached model-specific backends and heuristic fallback
|
|
||||||
- [x] Raw context inspection command
|
|
||||||
- [x] Plugin cache snapshot injection
|
|
||||||
- [x] Manifest-based plugin runtime summary injection
|
|
||||||
- [x] Manifest-based hook/policy summary injection
|
|
||||||
- [x] Trust-mode, managed-settings, and safe-env context injection
|
|
||||||
- [x] Manifest-based MCP runtime summary injection
|
|
||||||
- [x] Manifest-based MCP transport server summary injection
|
|
||||||
- [x] Manifest-based remote runtime summary injection
|
|
||||||
- [x] Manifest/env-based search runtime summary injection
|
|
||||||
- [x] Manifest-based account runtime summary injection
|
|
||||||
- [x] Local LSP runtime summary injection
|
|
||||||
- [x] Manifest-based plan runtime summary injection
|
|
||||||
- [x] Manifest-based task runtime summary injection
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full tokenizer/chat-message framing parity beyond the current model-aware text token counters
|
|
||||||
- [ ] Full parity with `utils/queryContext.ts` (context analysis, suggestions, cache shaping)
|
|
||||||
- [x] Session memory compact (`services/SessionMemory/` partial) → `src/session_memory_compact.py` — remaining: background LLM extraction, full template handling
|
|
||||||
- [ ] Internal permission-aware memory handling
|
|
||||||
- [ ] Resume-aware prompt cache shaping used upstream
|
|
||||||
- [ ] More exact context cache invalidation rules
|
|
||||||
- [ ] Session context analysis parity (`utils/contextAnalysis.ts`, `utils/contextSuggestions.ts`)
|
|
||||||
- [ ] Full memory subsystem parity (`utils/memory/`, `services/extractMemories/`)
|
|
||||||
- [ ] Memory extraction from conversations (`services/extractMemories/extractMemories.ts`)
|
|
||||||
- [ ] Team memory sync (`services/teamMemorySync/`)
|
|
||||||
- [ ] Away summary generation (`services/awaySummary.ts`)
|
|
||||||
- [ ] Token estimation service (`services/tokenEstimation.ts`)
|
|
||||||
- [ ] Paste content storage and reference parsing (`history.ts`)
|
|
||||||
- [ ] Image paste handling
|
|
||||||
|
|
||||||
## 5. Slash Commands
|
|
||||||
|
|
||||||
Done (53 slash command names in 37 specs):
|
|
||||||
|
|
||||||
- [x] `/help`, `/commands`
|
|
||||||
- [x] `/context`, `/usage`
|
|
||||||
- [x] `/context-raw`, `/env`
|
|
||||||
- [x] `/token-budget`, `/budget`
|
|
||||||
- [x] `/mcp` (with subcommands: `tools`, `tool <name>`)
|
|
||||||
- [x] `/search` (with subcommands: `providers`, `provider`, `use`)
|
|
||||||
- [x] `/remote` (with `enter`, `exit`)
|
|
||||||
- [x] `/worktree` (with `enter`, `exit`)
|
|
||||||
- [x] `/account` (with `profiles`, `profile`)
|
|
||||||
- [x] `/ask` (with `history`)
|
|
||||||
- [x] `/login`
|
|
||||||
- [x] `/logout`
|
|
||||||
- [x] `/config`, `/settings` (with `effective`, `source`, `get`, `set`)
|
|
||||||
- [x] `/remotes`
|
|
||||||
- [x] `/ssh`
|
|
||||||
- [x] `/teleport`
|
|
||||||
- [x] `/direct-connect`
|
|
||||||
- [x] `/deep-link`
|
|
||||||
- [x] `/disconnect`, `/remote-disconnect`
|
|
||||||
- [x] `/resources`
|
|
||||||
- [x] `/resource`
|
|
||||||
- [x] `/tasks`, `/todo`
|
|
||||||
- [x] `/workflows`, `/workflow`
|
|
||||||
- [x] `/triggers`, `/trigger`
|
|
||||||
- [x] `/teams`, `/team`, `/messages`
|
|
||||||
- [x] `/task-next`, `/next-task`
|
|
||||||
- [x] `/plan`, `/planner`
|
|
||||||
- [x] `/task`
|
|
||||||
- [x] `/prompt`, `/system-prompt`
|
|
||||||
- [x] `/permissions`
|
|
||||||
- [x] `/hooks`, `/policy`
|
|
||||||
- [x] `/trust`
|
|
||||||
- [x] `/model`
|
|
||||||
- [x] `/tools`
|
|
||||||
- [x] `/memory`
|
|
||||||
- [x] `/status`, `/session`
|
|
||||||
- [x] `/clear`
|
|
||||||
|
|
||||||
Missing npm slash commands (from `src/commands/` — 80+ commands total):
|
|
||||||
|
|
||||||
- [x] `/add-dir` — Add a new working directory
|
|
||||||
- [x] `/agents` — Inspect, create, update, and delete local agent definitions
|
|
||||||
- [x] `/branch` — Create a branch of the current conversation
|
|
||||||
- [x] `/bridge` — Connect for remote-control sessions (read-only status in this runtime)
|
|
||||||
- [x] `/btw` — Quick side question without interrupting main conversation
|
|
||||||
- [x] `/chrome` — Chrome extension settings
|
|
||||||
- [x] `/color` — Set the prompt bar color for this session
|
|
||||||
- [x] `/compact` — Clear history but keep a summary in context
|
|
||||||
- [x] `/copy` — Copy Claude's last response to clipboard
|
|
||||||
- [x] `/cost` — Show total cost and duration of session
|
|
||||||
- [x] `/desktop` — Continue session in Claude Desktop
|
|
||||||
- [x] `/diff` — View uncommitted changes and per-turn diffs
|
|
||||||
- [x] `/doctor` — Diagnose and verify installation and settings
|
|
||||||
- [x] `/effort` — Set effort level for model usage
|
|
||||||
- [x] `/exit` — Exit the REPL
|
|
||||||
- [x] `/export` — Export conversation to file or clipboard
|
|
||||||
- [x] `/extra-usage` — Configure extra usage for rate limits
|
|
||||||
- [x] `/fast` — Toggle fast mode
|
|
||||||
- [x] `/feedback` — Submit feedback (alias `/bug`)
|
|
||||||
- [x] `/files` — List all files currently in context
|
|
||||||
- [x] `/ide` — Manage IDE integrations and show status
|
|
||||||
- [x] `/install-github-app` — Set up GitHub Actions
|
|
||||||
- [x] `/install-slack-app` — Install Slack app
|
|
||||||
- [x] `/keybindings` — Open keybindings config file
|
|
||||||
- [x] `/mobile` — Mobile app store links (aliases `/ios`, `/android`)
|
|
||||||
- [x] `/output-style` — Deprecation pointer to `/config`
|
|
||||||
- [x] `/passes` — Passes management
|
|
||||||
- [x] `/plugin` — Plugin management (read-only listing)
|
|
||||||
- [x] `/pr-comments`, `/pr_comments` — Get comments from a GitHub PR (prompt-type)
|
|
||||||
- [x] `/privacy-settings` — View/update privacy settings
|
|
||||||
- [x] `/rate-limit-options` — Show options when rate limited
|
|
||||||
- [x] `/release-notes` — View release notes
|
|
||||||
- [x] `/reload-plugins` — Activate pending plugin changes
|
|
||||||
- [x] `/remote-env` — Configure default remote environment
|
|
||||||
- [x] `/remote-setup` — Remote setup configuration (gh auth status + Claude.ai/code link)
|
|
||||||
- [x] `/rename` — Rename current conversation
|
|
||||||
- [x] `/resume`, `/continue` — Resume a previous conversation
|
|
||||||
- [x] `/rewind`, `/checkpoint` — Restore code/conversation to a previous point
|
|
||||||
- [x] `/sandbox-toggle` — Toggle sandbox mode (alias `/sandbox`)
|
|
||||||
- [x] `/skills` — List available bundled skills (mirrors `commands/skills/SkillsMenu.tsx`; lists `bundled_skills.BUNDLED_SKILLS`, not slash commands)
|
|
||||||
- [x] `/stats` — Usage statistics and activity
|
|
||||||
- [x] `/stickers` — Order stickers
|
|
||||||
- [x] `/tag` — Toggle a searchable tag on the session
|
|
||||||
- [x] `/theme` — Change the theme
|
|
||||||
- [x] `/upgrade` — Upgrade to Max
|
|
||||||
- [x] `/vim` — Toggle Vim/Normal editing modes
|
|
||||||
- [x] `/voice` — Toggle voice mode
|
|
||||||
- [ ] Feature-gated: `/buddy`, `/fork`, `/peers`, `/proactive`, `/torch`, `/workflows` (full), etc.
|
|
||||||
- [ ] Internal: `/backfill-sessions`, `/break-cache`, `/bughunter`, `/commit-push-pr`, `/init-verifiers`, `/mock-limits`, `/version`, `/ultraplan`, `/autofix-pr`, etc.
|
|
||||||
- [x] `/commit` — Create a git commit (prompt-type with injected git context)
|
|
||||||
- [ ] Full `/agents` parity for interactive TUI/editor flows, plugin sources, and full multi-source management UX
|
|
||||||
|
|
||||||
## 6. Built-in Tools
|
|
||||||
|
|
||||||
### Tools implemented in Python (65 tools):
|
|
||||||
|
|
||||||
- [x] `list_dir`
|
|
||||||
- [x] `read_file`
|
|
||||||
- [x] `write_file`
|
|
||||||
- [x] `edit_file`
|
|
||||||
- [x] `notebook_edit`
|
|
||||||
- [x] `glob_search`
|
|
||||||
- [x] `grep_search`
|
|
||||||
- [x] `bash`
|
|
||||||
- [x] `web_fetch`
|
|
||||||
- [x] `search_status`
|
|
||||||
- [x] `search_list_providers`
|
|
||||||
- [x] `search_activate_provider`
|
|
||||||
- [x] `web_search`
|
|
||||||
- [x] `LSP`
|
|
||||||
- [x] `tool_search`
|
|
||||||
- [x] `sleep`
|
|
||||||
- [x] `ask_user_question`
|
|
||||||
- [x] `account_status`
|
|
||||||
- [x] `account_list_profiles`
|
|
||||||
- [x] `account_login`
|
|
||||||
- [x] `account_logout`
|
|
||||||
- [x] `config_list`
|
|
||||||
- [x] `config_get`
|
|
||||||
- [x] `config_set`
|
|
||||||
- [x] `mcp_list_resources`
|
|
||||||
- [x] `mcp_read_resource`
|
|
||||||
- [x] `mcp_list_tools`
|
|
||||||
- [x] `mcp_call_tool`
|
|
||||||
- [x] `remote_status`
|
|
||||||
- [x] `remote_list_profiles`
|
|
||||||
- [x] `remote_connect`
|
|
||||||
- [x] `remote_disconnect`
|
|
||||||
- [x] `worktree_status`
|
|
||||||
- [x] `worktree_enter`
|
|
||||||
- [x] `worktree_exit`
|
|
||||||
- [x] `workflow_list`
|
|
||||||
- [x] `workflow_get`
|
|
||||||
- [x] `workflow_run`
|
|
||||||
- [x] `remote_trigger`
|
|
||||||
- [x] `plan_get`
|
|
||||||
- [x] `update_plan`
|
|
||||||
- [x] `plan_clear`
|
|
||||||
- [x] `task_next`
|
|
||||||
- [x] `task_list`
|
|
||||||
- [x] `task_get`
|
|
||||||
- [x] `task_create`
|
|
||||||
- [x] `task_update`
|
|
||||||
- [x] `task_start`
|
|
||||||
- [x] `task_complete`
|
|
||||||
- [x] `task_block`
|
|
||||||
- [x] `task_cancel`
|
|
||||||
- [x] `todo_write`
|
|
||||||
- [x] `delegate_agent`
|
|
||||||
- [x] `team_list`
|
|
||||||
- [x] `team_get`
|
|
||||||
- [x] `team_create`
|
|
||||||
- [x] `team_delete`
|
|
||||||
- [x] `send_message`
|
|
||||||
- [x] `team_messages`
|
|
||||||
- [x] `EnterPlanMode`
|
|
||||||
- [x] `ExitPlanMode`
|
|
||||||
- [x] `TaskOutput`
|
|
||||||
- [x] `TaskStop`
|
|
||||||
|
|
||||||
### Tools in npm `tools.ts` not yet ported with full fidelity (40 tool dirs):
|
|
||||||
|
|
||||||
Core tools needing full port:
|
|
||||||
- [x] `AgentTool` — Sub-agent spawning with built-in agents (explore, general-purpose, verification, plan, claudeCodeGuide, statusline) → `src/builtin_agents.py` — remaining: fork support, agent memory/snapshots, resume agent, color management
|
|
||||||
- [x] `SkillTool` — Skill execution via slash commands and bundled skills → `src/agent_tools.py`, `src/agent_runtime.py`, `src/bundled_skills.py` — remaining: forked skill execution
|
|
||||||
- [ ] `BriefTool` — Brief mode with attachments and file upload
|
|
||||||
- [ ] `LSPTool` — Full upstream LSP fidelity beyond the current local heuristic runtime (server-backed diagnostics, go-to-definition, references, hover, symbol search, formatting)
|
|
||||||
- [ ] `PowerShellTool` — Full PowerShell execution with security, path validation, CLM types, git safety
|
|
||||||
- [ ] `REPLTool` — Interactive REPL with primitive tools (ant-only)
|
|
||||||
- [ ] `MCPTool` — Full MCP tool execution with collapse classification
|
|
||||||
- [ ] `McpAuthTool` — MCP authentication handling
|
|
||||||
- [ ] `ConfigTool` — Full config management with supported settings list
|
|
||||||
- [ ] `SyntheticOutputTool` — Synthetic output injection
|
|
||||||
- [x] `EnterPlanModeTool` — Enter plan mode → `src/agent_tools.py`
|
|
||||||
- [x] `ExitPlanModeTool` — Exit plan mode → `src/agent_tools.py`
|
|
||||||
- [ ] `EnterWorktreeTool` — Full worktree enter with UI
|
|
||||||
- [ ] `ExitWorktreeTool` — Full worktree exit with UI
|
|
||||||
- [x] `TaskOutputTool` — Task output display → `src/agent_tools.py`
|
|
||||||
- [x] `TaskStopTool` — Stop a running task → `src/agent_tools.py`
|
|
||||||
|
|
||||||
Feature-gated tools:
|
|
||||||
- [ ] `CronCreateTool` / `CronDeleteTool` / `CronListTool` — Cron scheduling (AGENT_TRIGGERS)
|
|
||||||
- [ ] `RemoteTriggerTool` — Full remote triggers with UI (AGENT_TRIGGERS_REMOTE)
|
|
||||||
- [ ] `MonitorTool` — MCP server monitoring (MONITOR_TOOL)
|
|
||||||
- [ ] `SendUserFileTool` — Send file to user (KAIROS)
|
|
||||||
- [ ] `PushNotificationTool` — Push notifications (KAIROS)
|
|
||||||
- [ ] `SubscribePRTool` — PR subscription (KAIROS_GITHUB_WEBHOOKS)
|
|
||||||
- [ ] `SuggestBackgroundPRTool` — Background PR (ant-only)
|
|
||||||
- [ ] `VerifyPlanExecutionTool` — Plan verification
|
|
||||||
- [ ] `TungstenTool` — Tungsten tool
|
|
||||||
- [ ] `WebBrowserTool` — Full web browser
|
|
||||||
- [ ] `TerminalCaptureTool` — Terminal capture
|
|
||||||
- [ ] `SnipTool` — Force history snipping
|
|
||||||
- [ ] `ListPeersTool` — List peers (UDS_INBOX)
|
|
||||||
- [ ] `EmbeddedSearchTool` — Embedded search
|
|
||||||
- [ ] `CtxInspectTool` — Context inspection
|
|
||||||
- [ ] `WorkflowTool` — Workflow scripts (WORKFLOW_SCRIPTS)
|
|
||||||
|
|
||||||
Note: Python has basic tool execution for `bash`, `read_file`, etc., but lacks per-tool UI components, prompt files, constants, and deep security validations (e.g., BashTool has 15 supporting files in npm).
|
|
||||||
|
|
||||||
## 7. Commands And Task Systems
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Basic local command dispatch for the Python runtime
|
|
||||||
- [x] Inventory view of mirrored command names
|
|
||||||
- [x] Local persistent task runtime with create/get/list/update flows
|
|
||||||
- [x] Local todo-list replacement flow
|
|
||||||
- [x] Local persistent plan runtime with get/update/clear flows
|
|
||||||
- [x] Local plan-to-task sync flow
|
|
||||||
- [x] Local dependency-aware task execution flow with next-task selection and blocked/unblocked state
|
|
||||||
- [x] Local remote profile/runtime flow with persisted connect/disconnect state
|
|
||||||
- [x] Local background task management for agent worker sessions
|
|
||||||
- [x] Local ask-user runtime with queued answers, history, and slash/CLI inspection flows
|
|
||||||
- [x] Local team runtime with persisted teams, messages, and slash/CLI inspection flows
|
|
||||||
- [x] Local workflow runtime with manifest discovery, run history, and workflow CLI/slash flows
|
|
||||||
- [x] Local remote trigger runtime with create/update/run flows and trigger CLI/slash flows
|
|
||||||
- [x] Local managed git worktree runtime with session cwd switching and worktree CLI/slash flows
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Real implementation of the larger upstream command tree (80+ commands)
|
|
||||||
- [ ] Task types: `LocalShellTask`, `LocalAgentTask`, `RemoteAgentTask`, `DreamTask`, `LocalWorkflowTask`, `MonitorMcpTask`, `InProcessTeammateTask`
|
|
||||||
- [ ] Task stall detection (45s threshold) and prompt detection for interactive input
|
|
||||||
- [ ] Remote agent task session URL tracking and completion checkers
|
|
||||||
- [ ] Dream/auto-consolidation task with file tracking and turn history
|
|
||||||
- [ ] Task orchestration system beyond the current local dependency-aware task runtime
|
|
||||||
- [ ] Planner / task execution parity beyond the current local plan persistence, sync, and next-task flow
|
|
||||||
- [ ] Team / collaboration command flows beyond the current local team runtime and message recording flows
|
|
||||||
- [ ] Command-specific session behaviors
|
|
||||||
- [ ] Full `src/commands/*` parity (80+ command directories)
|
|
||||||
- [ ] Full `src/tasks/*` parity (7 task types)
|
|
||||||
|
|
||||||
## 8. Permissions, Hooks, And Policy
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Read-only default mode
|
|
||||||
- [x] Write-gated mode
|
|
||||||
- [x] Shell-gated mode
|
|
||||||
- [x] Unsafe mode for destructive shell actions
|
|
||||||
- [x] Local hook/policy manifest discovery
|
|
||||||
- [x] Hook before-prompt and after-turn runtime handling
|
|
||||||
- [x] Hook/policy tool preflight, deny, and after-tool handling
|
|
||||||
- [x] Policy budget override loading
|
|
||||||
- [x] Managed settings loading and reporting
|
|
||||||
- [x] Safe environment loading for shell tool context
|
|
||||||
- [x] Trust reporting and hook/policy slash commands
|
|
||||||
- [x] Permission-denial runtime events for policy/tool blocks
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [x] Full BashTool security: `bashSecurity.ts`, `sedValidation.ts`, `sedEditParser.ts`, `pathValidation.ts`, `readOnlyValidation.ts`, `modeValidation.ts`, `commandSemantics.ts`, `destructiveCommandWarning.ts`, `shouldUseSandbox.ts` → `src/bash_security.py` (18 validators, destructive warnings, command semantics, read-only detection, 163 tests)
|
|
||||||
- [ ] Full PowerShellTool security: `powershellSecurity.ts`, `gitSafety.ts`, `clmTypes.ts`
|
|
||||||
- [ ] Tool-permission workflow parity (`bashPermissions.ts`, `powershellPermissions.ts`)
|
|
||||||
- [ ] Trust-gated initialization
|
|
||||||
- [ ] Hook-config management (`schemas/hooks.ts` with Zod schemas)
|
|
||||||
- [ ] Policy limits service (`services/policyLimits/`)
|
|
||||||
- [ ] Remote managed settings (`services/remoteManagedSettings/`)
|
|
||||||
- [ ] Full hooks and policy parity
|
|
||||||
|
|
||||||
## 9. MCP, Plugins, And Skills
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Placeholder mirrored package layout for plugins, skills, services, and remote subsystems
|
|
||||||
- [x] Local manifest-backed MCP discovery
|
|
||||||
- [x] Local MCP resource listing and reading
|
|
||||||
- [x] MCP-backed runtime tools for local resource access
|
|
||||||
- [x] Real MCP client support over local stdio transport
|
|
||||||
- [x] MCP server integration for stdio child-process servers
|
|
||||||
- [x] MCP-backed tool listing and execution over transport
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full MCP service (`services/mcp/` — 25+ files: InProcessTransport, MCPConnectionManager, SdkControlTransport, auth, channelAllowlist, channelPermissions, client, config, elicitationHandler, envExpansion, normalization, oauthPort, officialRegistry, vscodeSdkMcp, xaa, xaaIdpLogin, etc.)
|
|
||||||
- [ ] MCP server approval dialogs (`services/mcpServerApproval.tsx`)
|
|
||||||
- [ ] Plugin discovery, loading, and installation (`services/plugins/PluginInstallationManager.ts`, `pluginCliCommands.ts`, `pluginOperations.ts`)
|
|
||||||
- [ ] Bundled plugin support (`plugins/bundledPlugins.ts`, `plugins/bundled/`)
|
|
||||||
- [ ] Plugin lifecycle management
|
|
||||||
- [ ] Plugin update/cache behavior
|
|
||||||
- [x] Skill discovery and execution → `src/bundled_skills.py` (simplify, verify, debug, update-config) — remaining: loadSkillsDir, mcpSkillBuilders, disk-based SKILL.md loading
|
|
||||||
- [x] Bundled skill support → `src/bundled_skills.py` — remaining: skillify, batch, loop, schedule, claude-api, chrome, and feature-gated skills
|
|
||||||
- [ ] Full plugin and skill parity
|
|
||||||
|
|
||||||
## 10. Interactive UI / REPL / TUI
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Non-interactive CLI execution
|
|
||||||
- [x] Basic interactive REPL-style agent chat loop
|
|
||||||
- [x] Transcript printing for debugging
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Interactive REPL parity (`screens/REPL.tsx`)
|
|
||||||
- [ ] Ink/TUI framework (`ink/` — 40+ files: custom renderer, reconciler, DOM, layout engine, text wrapping, ANSI handling, focus management, selection)
|
|
||||||
- [ ] Screen system (`screens/Doctor.tsx`, `screens/ResumeConversation.tsx`)
|
|
||||||
- [ ] Component library (`components/` — 100+ components in 12+ subdirectories):
|
|
||||||
- Message rendering: Message, MessageRow, Messages, MessageSelector, MessageResponse
|
|
||||||
- Dialogs: ApproveApiKey, AutoModeOptIn, Bridge, CostThreshold, IdeAutoConnect, MCPServerApproval
|
|
||||||
- Settings: ThemePicker, LanguagePicker, ModelPicker, OutputStylePicker
|
|
||||||
- Search: GlobalSearchDialog, QuickOpenDialog, HistorySearchDialog
|
|
||||||
- Status: AgentProgressLine, BashModeProgress, MemoryUsageIndicator, TokenWarning
|
|
||||||
- Design system, agent, team, task, skill, memory, permissions, sandbox, shell components
|
|
||||||
- [ ] Keyboard interaction parity
|
|
||||||
- [ ] Interactive status panes
|
|
||||||
- [ ] Approval UI flows
|
|
||||||
- [ ] Rich incremental rendering
|
|
||||||
- [ ] Virtual scrolling
|
|
||||||
- [ ] Copy-on-select behavior
|
|
||||||
|
|
||||||
## 11. Remote, Background, And Team Features
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Session save/resume on local disk
|
|
||||||
- [x] Local manifest-backed remote profile/runtime state
|
|
||||||
- [x] Local remote connect/disconnect session state
|
|
||||||
- [x] Local background agent processes
|
|
||||||
- [x] Local background attach/log/kill workflows
|
|
||||||
- [x] Local daemon-style wrapper over background agent sessions
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Real remote session management (`remote/` — 4 files: RemoteSessionManager, SessionsWebSocket, remotePermissionBridge, sdkMessageAdapter)
|
|
||||||
- [ ] Bridge subsystem (`bridge/` — 30+ files: bridgeMain, bridgeApi, bridgeConfig, bridgeMessaging, bridgePermissionCallbacks, replBridge, replBridgeHandle, replBridgeTransport, sessionRunner, trustedDevice, jwtUtils, capacityWake, inboundAttachments, inboundMessages, etc.)
|
|
||||||
- [ ] Direct connect subsystem (`server/createDirectConnectSession.ts`, `directConnectManager.ts`)
|
|
||||||
- [ ] Real team collaboration beyond local recording
|
|
||||||
- [ ] Shared remote state
|
|
||||||
- [ ] Upstream proxy (`upstreamproxy/upstreamproxy.ts`, `upstreamproxy/relay.ts`)
|
|
||||||
|
|
||||||
## 12. Editor, Platform, And Native Integrations
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Standard shell-based local workflow
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Voice mode (`voice/`, `services/voice.ts`, `services/voiceKeyterms.ts`, `services/voiceStreamSTT.ts`, hooks)
|
|
||||||
- [ ] VIM mode (`vim/` — 5 files: motions, operators, textObjects, transitions, types)
|
|
||||||
- [ ] Keybinding system (`keybindings/` — 13 files: defaultBindings, loadUserBindings, match, parser, resolver, schema, template, validate, etc.)
|
|
||||||
- [ ] Notification hooks (`services/notifier.ts`, `services/preventSleep.ts`)
|
|
||||||
- [ ] Native TypeScript / platform helpers (`native-ts/`)
|
|
||||||
- [ ] JetBrains/editor integration (`utils/jetbrains.ts`, `utils/ide.ts`, `utils/idePathConversion.ts`)
|
|
||||||
- [ ] Browser/native host integrations
|
|
||||||
- [ ] IDE integration hooks (useIDEIntegration, useIdeAtMentioned, useIdeSelection, useIdeLogging, useDiffInIDE, useLspPluginRecommendation)
|
|
||||||
- [ ] Platform-specific startup/shutdown logic
|
|
||||||
- [ ] Chrome extension integration
|
|
||||||
|
|
||||||
## 13. Services And Internal Subsystems
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Minimal internal service layer required by the current Python runtime
|
|
||||||
- [x] Local account/auth runtime for manifest-backed profile discovery and persisted login state
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Analytics service (`services/analytics/` — 10+ files: config, Datadog, Growthbook, first-party event logger, sink, killswitch)
|
|
||||||
- [ ] API service (`services/api/` — 20+ files: claude client, dumpPrompts, errorUtils, filesApi, firstTokenDate, grove, logging, metricsOptOut, promptCacheBreakDetection, sessionIngress, usage, withRetry, etc.)
|
|
||||||
- [ ] LSP service (`services/lsp/` — 7 files: LSPClient, LSPDiagnosticRegistry, LSPServerInstance, LSPServerManager, config, manager, passiveFeedback)
|
|
||||||
- [ ] Tools service (`services/tools/` — 4 files: StreamingToolExecutor, toolExecution, toolHooks, toolOrchestration)
|
|
||||||
- [ ] Compact service (`services/compact/` — 6 files) — partially ported: compact → `src/compact.py`, microCompact → `src/microcompact.py`, sessionMemoryCompact → `src/session_memory_compact.py`; remaining: autoCompact trigger, apiMicrocompact, compactWarningHook
|
|
||||||
- [ ] Auto-dream service (`services/autoDream/` — 4 files: autoDream, config, consolidationLock, consolidationPrompt)
|
|
||||||
- [ ] Agent summary service (`services/AgentSummary/`)
|
|
||||||
- [ ] Magic docs service (`services/MagicDocs/`)
|
|
||||||
- [ ] Session memory service (`services/SessionMemory/`)
|
|
||||||
- [ ] Prompt suggestion service (`services/PromptSuggestion/`)
|
|
||||||
- [ ] Extract memories service (`services/extractMemories/`)
|
|
||||||
- [ ] Diagnostic tracking service (`services/diagnosticTracking.ts`)
|
|
||||||
- [ ] OAuth service (`services/oauth/` — 5 files)
|
|
||||||
- [ ] Rate limiting (`services/claudeAiLimits.ts`, `services/rateLimitMessages.ts`, etc.)
|
|
||||||
- [ ] Settings sync (`services/settingsSync/`)
|
|
||||||
- [ ] Tips service (`services/tips/`)
|
|
||||||
- [ ] Tool use summary service (`services/toolUseSummary/`)
|
|
||||||
- [ ] VCR playback (`services/vcr.ts`)
|
|
||||||
- [ ] Internal/container logging (`services/internalLogging.ts`)
|
|
||||||
- [ ] Plugin installation management (`services/plugins/`)
|
|
||||||
|
|
||||||
## 14. State Management
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Session state via `AgentSessionState` dataclass
|
|
||||||
- [x] Basic session persistence
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Zustand store (`state/AppStateStore.ts`, `state/store.ts`)
|
|
||||||
- [ ] Store selectors (`state/selectors.ts`)
|
|
||||||
- [ ] State change callbacks (`state/onChangeAppState.ts`)
|
|
||||||
- [ ] React context providers (`state/AppState.tsx`)
|
|
||||||
|
|
||||||
## 15. React Hooks (84+ hooks in `src/hooks/`)
|
|
||||||
|
|
||||||
Not applicable for Python (no React TUI), but these represent features needing alternative implementations:
|
|
||||||
|
|
||||||
- [ ] File suggestions and unified suggestions
|
|
||||||
- [ ] Remote session / SSH / direct connect hooks
|
|
||||||
- [ ] Input buffer, text input, vim input, typeahead, search input, paste handling
|
|
||||||
- [ ] Arrow key history, history search, background task navigation
|
|
||||||
- [ ] Main loop model selection, assistant history, merged clients/commands/tools
|
|
||||||
- [ ] Tool permission checking, cancel request, manage plugins
|
|
||||||
- [ ] Global/command keybindings, exit handling, double-press detection
|
|
||||||
- [ ] Terminal size, virtual scroll, copy-on-select
|
|
||||||
- [ ] Voice recording, voice integration
|
|
||||||
- [ ] IDE integration, @mention, selection, diff-in-IDE
|
|
||||||
- [ ] Settings management, dynamic config
|
|
||||||
- [ ] Timeout, elapsed time, scheduled tasks, delayed notifications
|
|
||||||
- [ ] Prompt suggestion, update notification, feature hints
|
|
||||||
- [ ] Queue processor, command queue
|
|
||||||
- [ ] Memory usage, away summary, teleport resume
|
|
||||||
- [ ] Diff data, turn diffs
|
|
||||||
- [ ] Task list watcher, tasks v2, PR status
|
|
||||||
- [ ] Session backgrounding, swarm initialization/permission
|
|
||||||
- [ ] API key verification, mailbox bridge, inbox poller
|
|
||||||
|
|
||||||
## 16. Utilities (200+ files in `src/utils/`)
|
|
||||||
|
|
||||||
Done:
|
|
||||||
|
|
||||||
- [x] Basic file operations in tool implementations
|
|
||||||
- [x] Basic git status snapshot
|
|
||||||
- [x] Basic shell/subprocess handling
|
|
||||||
- [x] Bundled small portable utilities — `utils/array.ts`, `utils/set.ts`, `utils/objectGroupBy.ts`, `utils/xml.ts`, `utils/uuid.ts` ported in `src/small_utils.py`
|
|
||||||
- [x] Session-scoped env-var registry (`utils/sessionEnvVars.ts`) ported in `src/session_env_vars.py`, merged into spawned subprocess env via `_build_subprocess_env` (mirrors `utils/shell/bashProvider.ts`), and dropped on `/clear` via `clear_runtime_state` (mirrors `commands/clear/caches.ts`)
|
|
||||||
- [x] Display formatters from `utils/format.ts` (`formatFileSize`, `formatSecondsShort`, `formatDuration`, `formatNumber`, `formatTokens`) ported in `src/format_utils.py`
|
|
||||||
|
|
||||||
Missing major utility categories:
|
|
||||||
|
|
||||||
- [ ] Shell utilities (`utils/bash/`, `utils/shell/`, `Shell.ts`, `ShellCommand.ts`)
|
|
||||||
- [ ] Git operations (`utils/git.ts`, `utils/gitDiff.ts`, `utils/gitSettings.ts`, `utils/commitAttribution.ts`) — partial: `findGitRoot`, `normalizeGitRemoteUrl`, `getRepoRemoteHash`, and `shouldIncludeGitInstructions` ported in `src/git_utils.py`
|
|
||||||
- [ ] File operations (`utils/file.ts`, `utils/fileRead.ts`, `utils/fileHistory.ts`, `utils/fileStateCache.ts`, `utils/fsOperations.ts`, `utils/ripgrep.ts`, `utils/glob.ts`)
|
|
||||||
- [ ] AI/Model utilities (`utils/modelCost.ts`, `utils/model/`, `utils/context.ts`, `utils/queryContext.ts`) — partial: modelCost ported in `src/model_cost.py`
|
|
||||||
- [ ] Config/Settings (`utils/config.ts`, `utils/settings/`)
|
|
||||||
- [ ] Message handling (`utils/messages.ts`, `utils/messages/`, `utils/messageQueueManager.ts`)
|
|
||||||
- [ ] API/Network (`utils/api.ts`, `utils/http.ts`, `utils/proxy.ts`, `utils/auth.ts`)
|
|
||||||
- [ ] Session management (`utils/sessionStorage.ts`, `utils/sessionState.ts`, `utils/sessionStart.ts`, `utils/sessionRestore.ts`)
|
|
||||||
- [ ] Plugin/Skill utilities (`utils/plugins/`, `utils/skills/`)
|
|
||||||
- [ ] Memory/Context (`utils/memory/`, `utils/claudemd.ts`, `utils/contextAnalysis.ts`)
|
|
||||||
- [ ] IDE integration (`utils/ide.ts`, `utils/jetbrains.ts`) — partial: `utils/idePathConversion.ts` ported in `src/ide_path_conversion.py` (`WindowsToWSLConverter`, `checkWSLDistroMatch`)
|
|
||||||
- [ ] Platform/OS (`utils/platform.ts`, `utils/terminal.ts`, `utils/systemDirectories.ts`) — partial: platform detection (`getPlatform`, `getWslVersion`, `getLinuxDistroInfo`, `detectVcs`) and `getSystemDirectories` ported in `src/platform_info.py`
|
|
||||||
- [ ] Debugging (`utils/debug.ts`, `utils/diagLogs.ts`, `utils/log.ts`, `utils/profilerBase.ts`)
|
|
||||||
- [ ] Telemetry (`utils/telemetry/`)
|
|
||||||
- [ ] Deep link utilities (`utils/deepLink/`)
|
|
||||||
|
|
||||||
## 17. Coordinator And Buddy
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Coordinator mode (`coordinator/coordinatorMode.ts` — agent tool filtering and async agent allowlist)
|
|
||||||
- [ ] Buddy/companion system (`buddy/` — 6 files: CompanionSprite, companion procedural generation, personality prompts, sprites, types, notification UI)
|
|
||||||
|
|
||||||
## 18. Migrations
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Data/config migration system (`migrations/` — 11 migration scripts):
|
|
||||||
- Model migrations: migrateFennecToOpus, migrateLegacyOpusToCurrent, migrateOpusToOpus1m, migrateSonnet1mToSonnet45, migrateSonnet45ToSonnet46
|
|
||||||
- Feature migrations: migrateAutoUpdatesToSettings, migrateBypassPermissionsAcceptedToSettings, migrateEnableAllProjectMcpServersToSettings, migrateReplBridgeEnabledToRemoteControlAtStartup
|
|
||||||
- Config resets: resetAutoModeOptInForDefaultOffer, resetProToOpusDefault
|
|
||||||
|
|
||||||
## 19. Type Definitions
|
|
||||||
|
|
||||||
Missing:
|
|
||||||
|
|
||||||
- [ ] Full type system from `types/` (command.ts, hooks.ts, ids.ts, logs.ts, permissions.ts, plugin.ts, textInputTypes.ts, generated/)
|
|
||||||
|
|
||||||
## 20. Mirrored Workspace Versus Working Runtime
|
|
||||||
|
|
||||||
Working Python runtime today (21,193 lines across 51 source files, 10,480 lines across 37 test files):
|
|
||||||
|
|
||||||
- [x] `src/main.py` (1,353 lines)
|
|
||||||
- [x] `src/agent_runtime.py` (4,318 lines)
|
|
||||||
- [x] `src/agent_tools.py` (3,183 lines)
|
|
||||||
- [x] `src/agent_prompting.py` (390 lines)
|
|
||||||
- [x] `src/agent_context.py` (459 lines)
|
|
||||||
- [x] `src/agent_context_usage.py` (356 lines)
|
|
||||||
- [x] `src/agent_session.py` (718 lines)
|
|
||||||
- [x] `src/agent_slash_commands.py` (633 lines)
|
|
||||||
- [x] `src/agent_manager.py` (296 lines)
|
|
||||||
- [x] `src/agent_plugin_cache.py` (154 lines)
|
|
||||||
- [x] `src/agent_types.py` (193 lines)
|
|
||||||
- [x] `src/account_runtime.py` (470 lines)
|
|
||||||
- [x] `src/ask_user_runtime.py` (320 lines)
|
|
||||||
- [x] `src/background_runtime.py` (371 lines)
|
|
||||||
- [x] `src/config_runtime.py` (296 lines)
|
|
||||||
- [x] `src/hook_policy.py` (339 lines)
|
|
||||||
- [x] `src/mcp_runtime.py` (880 lines)
|
|
||||||
- [x] `src/openai_compat.py` (413 lines)
|
|
||||||
- [x] `src/permissions.py` (20 lines)
|
|
||||||
- [x] `src/plan_runtime.py` (396 lines)
|
|
||||||
- [x] `src/plugin_runtime.py` (654 lines)
|
|
||||||
- [x] `src/query_engine.py` (655 lines)
|
|
||||||
- [x] `src/remote_runtime.py` (571 lines)
|
|
||||||
- [x] `src/remote_trigger_runtime.py` (371 lines)
|
|
||||||
- [x] `src/search_runtime.py` (606 lines)
|
|
||||||
- [x] `src/session_store.py` (295 lines)
|
|
||||||
- [x] `src/task.py` (130 lines)
|
|
||||||
- [x] `src/task_runtime.py` (595 lines)
|
|
||||||
- [x] `src/team_runtime.py` (386 lines)
|
|
||||||
- [x] `src/tokenizer_runtime.py` (202 lines)
|
|
||||||
- [x] `src/workflow_runtime.py` (319 lines)
|
|
||||||
- [x] `src/worktree_runtime.py` (448 lines)
|
|
||||||
- [x] `src/builtin_agents.py` (426 lines)
|
|
||||||
- [x] `src/microcompact.py` (236 lines)
|
|
||||||
- [x] Plus 19 supporting modules
|
|
||||||
|
|
||||||
Mirrored / scaffold areas needing real implementation:
|
|
||||||
|
|
||||||
- [ ] `src/commands.py` — currently minimal dispatch, needs full command tree
|
|
||||||
- [ ] `src/tools.py` — reference-data based tool loading, needs real per-tool implementations
|
|
||||||
- [ ] `src/query_engine.py` — facade layer, needs full QueryEngine.ts parity
|
|
||||||
- [ ] `src/runtime.py` — routing layer, needs full runtime parity
|
|
||||||
- [ ] Remaining inventory surfaces under `src/reference_data/*`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## High-Priority Next Steps
|
|
||||||
|
|
||||||
### Tier 1 — Core Feature Gaps (highest user impact)
|
|
||||||
- [x] Full BashTool security parity (sed validation, path validation, sandbox, destructive command warnings, command semantics) → `src/bash_security.py`
|
|
||||||
- [x] LSP tool integration for code intelligence
|
|
||||||
- [x] Full AgentTool with built-in agent types (explore, general-purpose, verification, plan, statusline-setup, claude-code-guide) → `src/builtin_agents.py`, `src/agent_tools.py`, `src/agent_runtime.py`
|
|
||||||
- [ ] Auto-compact and context collapse from `query.ts`
|
|
||||||
- [x] Microcompact service (time-based tool-result clearing) → `src/microcompact.py`
|
|
||||||
- [x] Compact PTL retry loop and circuit-breaker tracking → `src/compact.py`
|
|
||||||
- [ ] Full compact service (sessionMemoryCompact, cached microcompact)
|
|
||||||
- [ ] Interactive REPL improvements
|
|
||||||
|
|
||||||
### Tier 2 — Important Feature Gaps
|
|
||||||
- [x] SkillTool for slash command execution → `src/agent_tools.py`, `src/agent_runtime.py`
|
|
||||||
- [ ] Full MCP service parity (auth, permissions, config, registry)
|
|
||||||
- [ ] Plugin discovery, loading, and installation
|
|
||||||
- [ ] Real remote session management (WebSocket, bridge)
|
|
||||||
- [ ] Full command tree implementation (80+ commands)
|
|
||||||
- [ ] Migration system for config/model upgrades
|
|
||||||
- [ ] Token budget calculations
|
|
||||||
|
|
||||||
### Tier 3 — Nice-to-Have Features
|
|
||||||
- [x] Local web GUI (FastAPI + vanilla JS SPA) → `src/gui/__main__.py`, `backend/api/server.py`, `frontend/legacy-static/*`; launch with `python -m src.gui` or `claw-code-gui`
|
|
||||||
- [ ] TUI/Ink component library
|
|
||||||
- [ ] Voice mode
|
|
||||||
- [ ] VIM mode and keybinding system
|
|
||||||
- [ ] IDE integrations (JetBrains, VS Code)
|
|
||||||
- [ ] Chrome extension integration
|
|
||||||
- [ ] Buddy/companion system
|
|
||||||
- [ ] Analytics/telemetry
|
|
||||||
- [ ] Coordinator mode
|
|
||||||
- [ ] Feature flag system (Growthbook)
|
|
||||||
|
|
||||||
### Tier 4 — Platform/Enterprise Features
|
|
||||||
- [ ] Full bridge subsystem (30+ files)
|
|
||||||
- [ ] Upstream proxy
|
|
||||||
- [ ] Direct connect server
|
|
||||||
- [ ] OAuth service
|
|
||||||
- [ ] Settings sync
|
|
||||||
- [ ] Rate limiting and policy limits
|
|
||||||
- [ ] Dream/auto-consolidation service
|
|
||||||
-1879
File diff suppressed because it is too large
Load Diff
@@ -1,845 +0,0 @@
|
|||||||
<p align="center">
|
|
||||||
<img src="images/logo.png" alt="Claw Code Agent logo" width="420" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h1 align="center">Claw Code Agent</h1>
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<em>A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies.</em>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
|
|
||||||
<a href="https://github.com/HarnessLab/claw-code-agent"><img src="https://img.shields.io/badge/repo-HarnessLab%2Fclaw--code--agent-181717?logo=github" alt="GitHub"></a>
|
|
||||||
<a href="https://docs.vllm.ai/"><img src="https://img.shields.io/badge/backend-vLLM-FF6F00?logo=lightning&logoColor=white" alt="vLLM"></a>
|
|
||||||
<a href="https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct"><img src="https://img.shields.io/badge/model-Qwen3--Coder-FFD21E?logo=huggingface&logoColor=black" alt="Qwen3-Coder"></a>
|
|
||||||
<img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero Dependencies">
|
|
||||||
<img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha">
|
|
||||||
<img src="https://img.shields.io/badge/license-open--source-green" alt="License">
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📢 What's New
|
|
||||||
|
|
||||||
> **April 2026 — Major Update**
|
|
||||||
|
|
||||||
| | Feature | Details |
|
|
||||||
|---|---------|---------|
|
|
||||||
| 🆕 | **Interactive Chat Mode** | New `agent-chat` command — multi-turn REPL with `/exit` to quit |
|
|
||||||
| 🆕 | **Streaming Output** | Token-by-token streaming with `--stream` flag |
|
|
||||||
| 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking |
|
|
||||||
| 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
|
|
||||||
| 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents |
|
|
||||||
| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool |
|
|
||||||
| 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits |
|
|
||||||
| 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` |
|
|
||||||
| 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors |
|
|
||||||
| 🆕 | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume |
|
|
||||||
| 🆕 | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) |
|
|
||||||
| 🆕 | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API |
|
|
||||||
| 🆕 | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider |
|
|
||||||
| 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint |
|
|
||||||
| 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports |
|
|
||||||
| 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows |
|
|
||||||
| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides |
|
|
||||||
| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution |
|
|
||||||
| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling |
|
|
||||||
| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows |
|
|
||||||
| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state |
|
|
||||||
| 🆕 | **Ask-User Runtime** | Queued or interactive local ask-user flow with history, slash commands, and agent tool support |
|
|
||||||
| 🆕 | **Team Runtime** | Persisted local teams and message history with team/message tools and slash/CLI inspection |
|
|
||||||
| 🆕 | **Notebook Edit Tool** | Native `.ipynb` cell editing through the real agent tool registry |
|
|
||||||
| 🆕 | **Workflow Runtime** | Manifest-backed local workflows with workflow tools, slash commands, and run history |
|
|
||||||
| 🆕 | **Remote Trigger Runtime** | Local remote triggers with create/update/run flows similar to the npm remote trigger surface |
|
|
||||||
| 🆕 | **Worktree Runtime** | Managed git worktrees with mid-session cwd switching, slash commands, and CLI flows |
|
|
||||||
| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
|
|
||||||
| 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures |
|
|
||||||
| 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics |
|
|
||||||
| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel |
|
|
||||||
| 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
|
|
||||||
| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
|
|
||||||
| 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
|
|
||||||
| 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📖 About
|
|
||||||
|
|
||||||
This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server.
|
|
||||||
|
|
||||||
Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent).
|
|
||||||
|
|
||||||
> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python — prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution.
|
|
||||||
>
|
|
||||||
> **Zero external dependencies** — just Python's standard library.
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<img src="images/demo_2.gif" alt="Claw Code Agent demo" width="900" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✨ Key Features
|
|
||||||
|
|
||||||
| Feature | Description |
|
|
||||||
|---------|-------------|
|
|
||||||
| 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
|
|
||||||
| 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity |
|
|
||||||
| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings |
|
|
||||||
| 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
|
|
||||||
| 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
|
|
||||||
| 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
|
|
||||||
| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` |
|
|
||||||
| 📡 **Streaming** | Token-by-token streaming output with `--stream` |
|
|
||||||
| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
|
|
||||||
| 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
|
|
||||||
| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
|
|
||||||
| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools |
|
|
||||||
| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting |
|
|
||||||
| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state |
|
|
||||||
| 🙋 **Ask-User Runtime** | Queued answer or interactive user-question flow with history tracking |
|
|
||||||
| 👥 **Team Runtime** | Persisted local teams plus message history, handoff notes, and collaboration metadata |
|
|
||||||
| 📓 **Notebook Editing** | Native Jupyter notebook cell editing through `notebook_edit` |
|
|
||||||
| 🪵 **Worktree Runtime** | Managed git worktrees with `worktree_enter`, `worktree_exit`, and live cwd switching |
|
|
||||||
| 🧭 **Workflow Runtime** | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs |
|
|
||||||
| ⏰ **Remote Triggers** | Local remote triggers with create/update/run flows and npm-style trigger actions |
|
|
||||||
| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
|
|
||||||
| 🧠 **LSP Code Intelligence** | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy |
|
|
||||||
| 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
|
|
||||||
| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics |
|
|
||||||
| 📏 **Prompt Budgeting** | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse |
|
|
||||||
| 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay |
|
|
||||||
| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill |
|
|
||||||
| 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps |
|
|
||||||
| 📋 **Structured Output** | JSON schema response mode for programmatic use |
|
|
||||||
| 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
|
|
||||||
| 🏗️ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter — any OpenAI-compatible API |
|
|
||||||
| 🐉 **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM |
|
|
||||||
| 📦 **Zero Dependencies** | Pure Python standard library — nothing to install |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 Roadmap
|
|
||||||
|
|
||||||
### 📚 Documentation
|
|
||||||
|
|
||||||
| Document | Description |
|
|
||||||
|----------|-------------|
|
|
||||||
| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature |
|
|
||||||
| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source |
|
|
||||||
|
|
||||||
### ✅ Done
|
|
||||||
|
|
||||||
- [x] Python CLI agent loop
|
|
||||||
- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL
|
|
||||||
- [x] OpenAI-compatible local model backend
|
|
||||||
- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser
|
|
||||||
- [x] Ollama, LiteLLM Proxy, and OpenRouter backends
|
|
||||||
- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
|
|
||||||
- [x] Context building and `/context`-style usage reporting
|
|
||||||
- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear`
|
|
||||||
- [x] Session persistence and `agent-resume` flow
|
|
||||||
- [x] Permission system (read-only, write, shell, unsafe tiers)
|
|
||||||
- [x] Streaming token-by-token assistant output
|
|
||||||
- [x] Truncated-response continuation flow
|
|
||||||
- [x] Auto-snip and auto-compact context reduction
|
|
||||||
- [x] Reactive compaction retry on prompt-too-long errors
|
|
||||||
- [x] Preflight prompt-length validation and token-budget reporting
|
|
||||||
- [x] Preflight auto-compact/context collapse before backend prompt-too-long failures
|
|
||||||
- [x] Cost tracking and usage budget enforcement
|
|
||||||
- [x] Token, tool-call, model-call, and session-turn budgets
|
|
||||||
- [x] Structured output / JSON schema response mode
|
|
||||||
- [x] File history journaling with snapshot IDs and replay summaries
|
|
||||||
- [x] Nested agent delegation with dependency-aware topological batching
|
|
||||||
- [x] Agent manager with lineage tracking and group membership
|
|
||||||
- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence
|
|
||||||
- [x] Local custom-agent create/update/delete flows via CLI and `/agents`
|
|
||||||
- [x] Local daemon-style background command family
|
|
||||||
- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
|
|
||||||
- [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
|
|
||||||
- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides
|
|
||||||
- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation
|
|
||||||
- [x] Local LSP runtime: definitions, references, hover, symbols, diagnostics, and call hierarchy
|
|
||||||
- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows
|
|
||||||
- [x] Local ask-user runtime: queued answers, history, and ask-user CLI/slash flows
|
|
||||||
- [x] Local team runtime: persisted teams, team messages, and team CLI/slash flows
|
|
||||||
- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search`
|
|
||||||
- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls
|
|
||||||
- [x] Local task and plan runtimes with plan sync and dependency-aware task execution
|
|
||||||
- [x] Notebook edit tool in the real Python tool registry
|
|
||||||
- [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows
|
|
||||||
- [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection
|
|
||||||
- [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows
|
|
||||||
- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`)
|
|
||||||
- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
|
|
||||||
- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
|
|
||||||
- [x] Plugin lifecycle hooks: resume, persist, delegate phases
|
|
||||||
- [x] Plugin session-state persistence and resume restoration
|
|
||||||
- [x] Query engine facade driving the real Python runtime
|
|
||||||
- [x] Compaction metadata with lineage IDs and revision summaries
|
|
||||||
- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep`
|
|
||||||
- [x] Unit tests for the Python runtime
|
|
||||||
- [x] `pyproject.toml` packaging with `setuptools`
|
|
||||||
|
|
||||||
### 🔲 In Progress
|
|
||||||
|
|
||||||
- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support
|
|
||||||
- [ ] Full slash-command parity with npm runtime
|
|
||||||
- [ ] Full interactive REPL / TUI behavior
|
|
||||||
- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting
|
|
||||||
- [ ] Hooks system parity
|
|
||||||
- [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime
|
|
||||||
- [ ] Voice and VIM modes
|
|
||||||
- [ ] Editor and platform integrations
|
|
||||||
- [ ] Background and team features
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ Architecture
|
|
||||||
|
|
||||||
```text
|
|
||||||
claw-code/
|
|
||||||
├── README.md
|
|
||||||
├── TESTING_GUIDE.md # How to test every feature
|
|
||||||
├── PARITY_CHECKLIST.md # Implementation status vs npm source
|
|
||||||
├── pyproject.toml
|
|
||||||
├── .gitignore
|
|
||||||
├── images/
|
|
||||||
│ └── logo.png
|
|
||||||
├── src/ # Python implementation
|
|
||||||
│ ├── main.py # CLI entry point & argument parsing
|
|
||||||
│ ├── agent_runtime.py # Core agent loop (LocalCodingAgent)
|
|
||||||
│ ├── agent_tools.py # Tool definitions & execution engine
|
|
||||||
│ ├── agent_prompting.py # System prompt assembly
|
|
||||||
│ ├── agent_registry.py # Built-in + filesystem-backed custom agent discovery
|
|
||||||
│ ├── agent_context.py # Context building & CLAUDE.md discovery
|
|
||||||
│ ├── agent_context_usage.py # Context usage estimation & reporting
|
|
||||||
│ ├── agent_session.py # Session state management
|
|
||||||
│ ├── agent_slash_commands.py # Local slash command processing
|
|
||||||
│ ├── agent_manager.py # Nested agent lineage & group tracking
|
|
||||||
│ ├── agent_types.py # Shared dataclasses & type definitions
|
|
||||||
│ ├── openai_compat.py # OpenAI-compatible API client (streaming)
|
|
||||||
│ ├── plugin_runtime.py # Plugin manifest, hooks, aliases, virtual tools
|
|
||||||
│ ├── agent_plugin_cache.py # Plugin discovery & prompt injection cache
|
|
||||||
│ ├── session_store.py # Session serialization & persistence
|
|
||||||
│ ├── transcript.py # Transcript block export & mutation tracking
|
|
||||||
│ ├── query_engine.py # Query engine facade & runtime orchestration
|
|
||||||
│ ├── mcp_runtime.py # Local MCP discovery and stdio MCP transport
|
|
||||||
│ ├── search_runtime.py # Search providers and provider-backed web_search
|
|
||||||
│ ├── remote_runtime.py # Local remote profiles, connect/disconnect state, remote CLI support
|
|
||||||
│ ├── background_runtime.py # Local background sessions and daemon support
|
|
||||||
│ ├── account_runtime.py # Local account profiles, login/logout state, account CLI support
|
|
||||||
│ ├── ask_user_runtime.py # Local ask-user queued answers and interaction history
|
|
||||||
│ ├── config_runtime.py # Local workspace config/settings discovery and mutation
|
|
||||||
│ ├── lsp_runtime.py # Local LSP-style code intelligence and diagnostics
|
|
||||||
│ ├── token_budget.py # Prompt-window budgeting and preflight prompt-length validation
|
|
||||||
│ ├── plan_runtime.py # Persistent plan runtime and plan sync
|
|
||||||
│ ├── task_runtime.py # Persistent task runtime and task execution
|
|
||||||
│ ├── task.py # Task state model and task dataclasses
|
|
||||||
│ ├── team_runtime.py # Local teams, messages, and collaboration metadata
|
|
||||||
│ ├── workflow_runtime.py # Local workflow manifests and recorded workflow runs
|
|
||||||
│ ├── remote_trigger_runtime.py # Local remote trigger manifests and trigger run history
|
|
||||||
│ ├── worktree_runtime.py # Managed git worktree sessions and cwd switching
|
|
||||||
│ ├── hook_policy.py # Hook/policy manifests, trust, and safe env handling
|
|
||||||
│ ├── tokenizer_runtime.py # Tokenizer-aware context accounting backends
|
|
||||||
│ ├── permissions.py # Tool permission filtering
|
|
||||||
│ ├── cost_tracker.py # Cost & budget enforcement
|
|
||||||
│ ├── commands.py # Mirrored command inventory
|
|
||||||
│ ├── tools.py # Mirrored tool inventory
|
|
||||||
│ ├── runtime.py # Mirrored runtime facade
|
|
||||||
│ ├── reference_data/ # Mirrored inventory snapshots
|
|
||||||
│ └── gui/ # Local web GUI (FastAPI + vanilla JS SPA)
|
|
||||||
│ ├── __main__.py # `python -m src.gui` entry point
|
|
||||||
│ ├── server.py # FastAPI app and JSON endpoints
|
|
||||||
│ └── static/ # index.html, app.css, app.js
|
|
||||||
└── tests/ # Unit tests
|
|
||||||
├── test_agent_runtime.py
|
|
||||||
├── test_agent_context.py
|
|
||||||
├── test_agent_context_usage.py
|
|
||||||
├── test_agent_prompting.py
|
|
||||||
├── test_agent_slash_commands.py
|
|
||||||
├── test_main.py
|
|
||||||
├── test_query_engine_runtime.py
|
|
||||||
└── test_porting_workspace.py
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📦 Requirements
|
|
||||||
|
|
||||||
| Requirement | Details |
|
|
||||||
|-------------|---------|
|
|
||||||
| 🐍 Python | `3.10` or higher |
|
|
||||||
| 📚 Dependencies | **None** — pure Python standard library |
|
|
||||||
| 🖥️ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support |
|
|
||||||
| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Quick Start
|
|
||||||
|
|
||||||
### 1. Start vLLM with Qwen3-Coder
|
|
||||||
|
|
||||||
vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python -m vllm.entrypoints.openai.api_server \
|
|
||||||
--model Qwen/Qwen3-Coder-30B-A3B-Instruct \
|
|
||||||
--host 127.0.0.1 \
|
|
||||||
--port 8000 \
|
|
||||||
--enable-auto-tool-choice \
|
|
||||||
--tool-call-parser qwen3_xml
|
|
||||||
```
|
|
||||||
|
|
||||||
Verify the server is running:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl http://127.0.0.1:8000/v1/models
|
|
||||||
```
|
|
||||||
|
|
||||||
> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
|
|
||||||
|
|
||||||
### Optional: Use Ollama Instead of vLLM
|
|
||||||
|
|
||||||
`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ollama serve
|
|
||||||
ollama pull qwen3
|
|
||||||
```
|
|
||||||
|
|
||||||
Then configure:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
|
|
||||||
export OPENAI_API_KEY=ollama
|
|
||||||
export OPENAI_MODEL=qwen3
|
|
||||||
```
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
- prefer tool-capable models such as `qwen3`
|
|
||||||
- plain chat-only models are not enough for full agent behavior
|
|
||||||
- Ollama does not use the `vLLM` parser flags shown above
|
|
||||||
|
|
||||||
> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
|
|
||||||
|
|
||||||
### Optional: Use LiteLLM Proxy
|
|
||||||
|
|
||||||
`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
|
|
||||||
|
|
||||||
Quick start example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pip install 'litellm[proxy]'
|
|
||||||
litellm --model ollama/qwen3
|
|
||||||
```
|
|
||||||
|
|
||||||
LiteLLM Proxy runs on port `4000` by default. Then configure:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_BASE_URL=http://127.0.0.1:4000
|
|
||||||
export OPENAI_API_KEY=anything
|
|
||||||
export OPENAI_MODEL=ollama/qwen3
|
|
||||||
```
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
|
|
||||||
- tool use still depends on the underlying routed model and provider behavior
|
|
||||||
- if you configure a LiteLLM master key, use that instead of `anything`
|
|
||||||
|
|
||||||
> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
|
|
||||||
|
|
||||||
### Optional: Use OpenRouter
|
|
||||||
|
|
||||||
`claw-code-agent` can also work with [OpenRouter](https://openrouter.ai/), a cloud API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and others through a single OpenAI-compatible endpoint. No local model server required.
|
|
||||||
|
|
||||||
Configure:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
|
|
||||||
export OPENAI_API_KEY=sk-or-v1-your-key-here
|
|
||||||
export OPENAI_MODEL=openai/gpt-4o-mini
|
|
||||||
```
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
- sign up at [openrouter.ai](https://openrouter.ai/) and create an API key under [Keys](https://openrouter.ai/keys)
|
|
||||||
- model names use the `provider/model` format (e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`)
|
|
||||||
- tool calling support varies by model — check the [model list](https://openrouter.ai/models) for capabilities
|
|
||||||
- this sends your conversation (including file contents and shell output) to OpenRouter and the upstream provider — do not use with repos containing secrets or sensitive data
|
|
||||||
|
|
||||||
> 📚 **References:** [OpenRouter Docs](https://openrouter.ai/docs) · [Supported Models](https://openrouter.ai/models) · [API Keys](https://openrouter.ai/keys)
|
|
||||||
|
|
||||||
### 2. Configure Environment
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
|
|
||||||
export OPENAI_API_KEY=local-token
|
|
||||||
export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
|
|
||||||
```
|
|
||||||
|
|
||||||
### Use Another Model With vLLM
|
|
||||||
|
|
||||||
If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python -m vllm.entrypoints.openai.api_server \
|
|
||||||
--model your-model-name \
|
|
||||||
--host 127.0.0.1 \
|
|
||||||
--port 8000 \
|
|
||||||
--enable-auto-tool-choice \
|
|
||||||
--tool-call-parser your_parser
|
|
||||||
```
|
|
||||||
|
|
||||||
Then update:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_MODEL=your-model-name
|
|
||||||
```
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
- the documented path in this repository is `vLLM`
|
|
||||||
- the model must support tool calling well enough for agent use
|
|
||||||
- some model families require a different `--tool-call-parser`
|
|
||||||
- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
|
|
||||||
|
|
||||||
### 3. Run the Agent
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Read-only question
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Read src/agent_runtime.py and summarize how the loop works." \
|
|
||||||
--cwd .
|
|
||||||
|
|
||||||
# Write-enabled task
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Create TEST_QWEN_AGENT.md with one line: test ok" \
|
|
||||||
--cwd . --allow-write
|
|
||||||
|
|
||||||
# Shell-enabled task
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Run pwd and ls src, then summarize the result." \
|
|
||||||
--cwd . --allow-shell
|
|
||||||
|
|
||||||
# Interactive chat mode
|
|
||||||
python3 -m src.main agent-chat --cwd .
|
|
||||||
|
|
||||||
# Streaming output
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Explain the current architecture." \
|
|
||||||
--cwd . --stream
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠️ Usage
|
|
||||||
|
|
||||||
### Agent Commands
|
|
||||||
|
|
||||||
| Command | Description |
|
|
||||||
|---------|-------------|
|
|
||||||
| `agent <prompt>` | Run the agent with a prompt |
|
|
||||||
| `agent-chat [prompt]` | Start interactive multi-turn chat mode |
|
|
||||||
| `agent-bg <prompt>` | Run the agent in a local background session |
|
|
||||||
| `agent-ps` | List local background sessions |
|
|
||||||
| `agent-logs <id>` | Show background session logs |
|
|
||||||
| `agent-attach <id>` | Show the current background output snapshot |
|
|
||||||
| `agent-kill <id>` | Stop a background session |
|
|
||||||
| `daemon <subcommand>` | Daemon-style wrapper over local background sessions |
|
|
||||||
| `agent-prompt` | Show the assembled system prompt |
|
|
||||||
| `agent-context` | Show estimated context usage |
|
|
||||||
| `agent-context-raw` | Show the raw context snapshot |
|
|
||||||
| `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits |
|
|
||||||
| `agents [agent_type]` | List active local agent definitions or show one agent profile |
|
|
||||||
| `agents-create <agent_type>` | Create a project or user agent definition markdown file |
|
|
||||||
| `agents-update <agent_type>` | Update an existing project or user agent definition |
|
|
||||||
| `agents-delete <agent_type>` | Delete an existing project or user agent definition |
|
|
||||||
| `agent-resume <id> <prompt>` | Resume a saved session |
|
|
||||||
|
|
||||||
### Runtime Utility Commands
|
|
||||||
|
|
||||||
| Command | Description |
|
|
||||||
|---------|-------------|
|
|
||||||
| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime |
|
|
||||||
| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime |
|
|
||||||
| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state |
|
|
||||||
| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes |
|
|
||||||
| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings |
|
|
||||||
| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state |
|
|
||||||
|
|
||||||
### CLI Flags
|
|
||||||
|
|
||||||
| Flag | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `--cwd <path>` | Set the workspace directory |
|
|
||||||
| `--model <name>` | Override the model name |
|
|
||||||
| `--base-url <url>` | Override the API base URL |
|
|
||||||
| `--allow-write` | Allow the agent to modify files |
|
|
||||||
| `--allow-shell` | Allow the agent to execute shell commands |
|
|
||||||
| `--unsafe` | Allow destructive shell operations |
|
|
||||||
| `--stream` | Enable token-by-token streaming output |
|
|
||||||
| `--show-transcript` | Print the full message transcript |
|
|
||||||
| `--scratchpad-root <path>` | Override the scratchpad directory |
|
|
||||||
| `--system-prompt <text>` | Set a custom system prompt |
|
|
||||||
| `--append-system-prompt <text>` | Append to the system prompt |
|
|
||||||
| `--override-system-prompt <text>` | Replace the generated system prompt |
|
|
||||||
| `--add-dir <path>` | Add extra directories to context |
|
|
||||||
|
|
||||||
### Budget & Limit Flags
|
|
||||||
|
|
||||||
| Flag | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `--max-total-tokens <n>` | Total token budget |
|
|
||||||
| `--max-input-tokens <n>` | Input token budget |
|
|
||||||
| `--max-output-tokens <n>` | Output token budget |
|
|
||||||
| `--max-reasoning-tokens <n>` | Reasoning token budget |
|
|
||||||
| `--max-budget-usd <n>` | Maximum cost in USD |
|
|
||||||
| `--max-tool-calls <n>` | Maximum tool calls per run |
|
|
||||||
| `--max-delegated-tasks <n>` | Maximum delegated subtasks |
|
|
||||||
| `--max-model-calls <n>` | Maximum model API calls |
|
|
||||||
| `--max-session-turns <n>` | Maximum session turns |
|
|
||||||
| `--input-cost-per-million <n>` | Input token pricing |
|
|
||||||
| `--output-cost-per-million <n>` | Output token pricing |
|
|
||||||
|
|
||||||
### Context Control Flags
|
|
||||||
|
|
||||||
| Flag | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `--auto-snip-threshold <n>` | Auto-snip older messages at this token count |
|
|
||||||
| `--auto-compact-threshold <n>` | Auto-compact at this token count |
|
|
||||||
| `--compact-preserve-messages <n>` | Messages to preserve during compaction |
|
|
||||||
| `--disable-claude-md` | Disable CLAUDE.md discovery |
|
|
||||||
|
|
||||||
### Structured Output Flags
|
|
||||||
|
|
||||||
| Flag | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `--response-schema-file <path>` | JSON schema file for structured output |
|
|
||||||
| `--response-schema-name <name>` | Schema name identifier |
|
|
||||||
| `--response-schema-strict` | Enforce strict schema validation |
|
|
||||||
|
|
||||||
### Slash Commands
|
|
||||||
|
|
||||||
These are handled **locally** before the model loop:
|
|
||||||
|
|
||||||
| Command | Aliases | Description |
|
|
||||||
|---------|---------|-------------|
|
|
||||||
| `/help` | `/commands` | Show built-in slash commands |
|
|
||||||
| `/context` | `/usage` | Show estimated session context usage |
|
|
||||||
| `/context-raw` | `/env` | Show raw environment & context snapshot |
|
|
||||||
| `/token-budget` | `/budget` | Show prompt-window budget, reserves, and soft/hard input limits |
|
|
||||||
| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool |
|
|
||||||
| `/resources` | — | List MCP resources |
|
|
||||||
| `/resource` | — | Read an MCP resource by URI |
|
|
||||||
| `/search` | — | Show search status, providers, activate a provider, or run a search |
|
|
||||||
| `/remote` | — | Show local remote status or activate a target |
|
|
||||||
| `/remotes` | — | List local remote profiles |
|
|
||||||
| `/ssh` | — | Activate an SSH-style remote profile |
|
|
||||||
| `/teleport` | — | Activate a teleport-style remote profile |
|
|
||||||
| `/direct-connect` | — | Activate a direct-connect remote profile |
|
|
||||||
| `/deep-link` | — | Activate a deep-link remote profile |
|
|
||||||
| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target |
|
|
||||||
| `/account` | — | Show account runtime status or profiles |
|
|
||||||
| `/login` | — | Activate a local account profile or identity |
|
|
||||||
| `/logout` | — | Clear the active account session |
|
|
||||||
| `/config` | `/settings` | Inspect effective config, sources, or a single config value |
|
|
||||||
| `/plan` | `/planner` | Show the local plan runtime state |
|
|
||||||
| `/tasks` | `/todo` | Show the local task list |
|
|
||||||
| `/task` | — | Show a task by id |
|
|
||||||
| `/task-next` | `/next-task` | Show the next actionable tasks |
|
|
||||||
| `/prompt` | `/system-prompt` | Render the effective system prompt |
|
|
||||||
| `/hooks` | `/policy` | Show local hook/policy manifests |
|
|
||||||
| `/trust` | — | Show trust mode, managed settings, and safe env values |
|
|
||||||
| `/permissions` | — | Show active tool permission mode |
|
|
||||||
| `/model` | — | Show or update the active model |
|
|
||||||
| `/tools` | — | List registered tools with permission status |
|
|
||||||
| `/agents` | — | List, show, create, update, or delete local agent definitions |
|
|
||||||
| `/memory` | — | Show loaded CLAUDE.md memory bundle |
|
|
||||||
| `/status` | `/session` | Show runtime/session status summary |
|
|
||||||
| `/clear` | — | Clear ephemeral runtime state |
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent "/help"
|
|
||||||
python3 -m src.main agent "/context" --cwd .
|
|
||||||
python3 -m src.main agent "/token-budget" --cwd .
|
|
||||||
python3 -m src.main agent "/tools" --cwd .
|
|
||||||
python3 -m src.main agent "/agents" --cwd .
|
|
||||||
python3 -m src.main agent "/status" --cwd .
|
|
||||||
```
|
|
||||||
|
|
||||||
### Custom Agent Definitions
|
|
||||||
|
|
||||||
Custom agent profiles can live in either of these directories:
|
|
||||||
|
|
||||||
- `./.claude/agents/*.md`
|
|
||||||
- `~/.claude/agents/*.md`
|
|
||||||
|
|
||||||
Project agents override user agents, and user agents override built-ins when the `agent_type` matches.
|
|
||||||
|
|
||||||
Example agent file:
|
|
||||||
|
|
||||||
```md
|
|
||||||
---
|
|
||||||
name: reviewer
|
|
||||||
description: "Review implementation changes carefully."
|
|
||||||
tools: read_file, grep_search
|
|
||||||
model: Qwen/Qwen3-Coder-30B-A3B-Instruct
|
|
||||||
initialPrompt: Start by identifying the highest-risk files.
|
|
||||||
---
|
|
||||||
|
|
||||||
Inspect code changes and summarize correctness risks, regressions, and missing tests.
|
|
||||||
```
|
|
||||||
|
|
||||||
Inspect the loaded profiles:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agents --cwd .
|
|
||||||
python3 -m src.main agents reviewer --cwd .
|
|
||||||
python3 -m src.main agent "/agents" --cwd .
|
|
||||||
python3 -m src.main agent "/agents show reviewer" --cwd .
|
|
||||||
```
|
|
||||||
|
|
||||||
Create, update, or delete agent files from the CLI:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agents-create reviewer \
|
|
||||||
--cwd . \
|
|
||||||
--description "Review implementation changes carefully." \
|
|
||||||
--prompt "Inspect code changes and summarize risks." \
|
|
||||||
--tools read_file,grep_search \
|
|
||||||
--model Qwen/Qwen3-Coder-30B-A3B-Instruct
|
|
||||||
|
|
||||||
python3 -m src.main agents-update reviewer \
|
|
||||||
--cwd . \
|
|
||||||
--description "Review implementation changes and tests carefully." \
|
|
||||||
--prompt "Focus on regressions, missing tests, and risky diffs."
|
|
||||||
|
|
||||||
python3 -m src.main agents-delete reviewer --cwd . --source project
|
|
||||||
```
|
|
||||||
|
|
||||||
Or use the local slash command management forms:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent "/agents create reviewer :: Review implementation changes carefully. :: Inspect code changes and summarize risks." --cwd .
|
|
||||||
python3 -m src.main agent "/agents update reviewer Updated review description :: Focus on regressions and missing tests." --cwd .
|
|
||||||
python3 -m src.main agent "/agents delete reviewer" --cwd .
|
|
||||||
```
|
|
||||||
|
|
||||||
### Utility Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main summary # Workspace summary
|
|
||||||
python3 -m src.main manifest # Workspace manifest
|
|
||||||
python3 -m src.main commands --limit 10 # Command inventory
|
|
||||||
python3 -m src.main tools --limit 10 # Tool inventory
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 Built-in Tools
|
|
||||||
|
|
||||||
The runtime currently includes core and extended tools:
|
|
||||||
|
|
||||||
| Tool | Description | Permission |
|
|
||||||
|------|-------------|------------|
|
|
||||||
| `list_dir` | List files and directories | 🟢 Always |
|
|
||||||
| `read_file` | Read file contents (with line ranges) | 🟢 Always |
|
|
||||||
| `write_file` | Write or create files | 🟡 `--allow-write` |
|
|
||||||
| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
|
|
||||||
| `glob_search` | Find files by glob pattern | 🟢 Always |
|
|
||||||
| `grep_search` | Search file contents by regex | 🟢 Always |
|
|
||||||
| `bash` | Execute shell commands | 🔴 `--allow-shell` |
|
|
||||||
| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always |
|
|
||||||
| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always |
|
|
||||||
| `tool_search` | Search the current Python tool registry | 🟢 Always |
|
|
||||||
| `sleep` | Bounded local wait tool | 🟢 Always |
|
|
||||||
| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` |
|
|
||||||
| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always |
|
|
||||||
| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always |
|
|
||||||
| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always |
|
|
||||||
| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` |
|
|
||||||
| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` |
|
|
||||||
| `delegate_agent` | Delegate work to nested child agents | 🟢 Always |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔌 Plugin System
|
|
||||||
|
|
||||||
Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "my-plugin",
|
|
||||||
"hooks": {
|
|
||||||
"beforePrompt": "Inject guidance into the system prompt.",
|
|
||||||
"afterTurn": "Run after each agent turn.",
|
|
||||||
"onResume": "Reapply state on session resume.",
|
|
||||||
"beforePersist": "Save state before session is saved.",
|
|
||||||
"beforeDelegate": "Inject guidance before child agents.",
|
|
||||||
"afterDelegate": "Process child agent results."
|
|
||||||
},
|
|
||||||
"toolAliases": [
|
|
||||||
{ "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." }
|
|
||||||
],
|
|
||||||
"virtualTools": [
|
|
||||||
{ "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" }
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🪆 Nested Agent Delegation
|
|
||||||
|
|
||||||
The agent can delegate subtasks to child agents with full context carryover:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Delegate a subtask to inspect src/agent_runtime.py and return a summary." \
|
|
||||||
--cwd . --show-transcript
|
|
||||||
```
|
|
||||||
|
|
||||||
Features:
|
|
||||||
- Sequential and parallel subtask execution
|
|
||||||
- Dependency-aware topological batching
|
|
||||||
- Child-session save and resume
|
|
||||||
- Agent manager lineage tracking
|
|
||||||
|
|
||||||
> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🖥️ Local Web GUI
|
|
||||||
|
|
||||||
If the terminal isn't your thing, launch the bundled browser GUI:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.gui --cwd . --allow-write --allow-shell
|
|
||||||
```
|
|
||||||
|
|
||||||
Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI.
|
|
||||||
|
|
||||||
| Flag | Description |
|
|
||||||
|------|-------------|
|
|
||||||
| `--host <addr>` | Bind address (default `127.0.0.1`) |
|
|
||||||
| `--port <n>` | Port to listen on (default `8765`) |
|
|
||||||
| `--cwd <path>` | Workspace directory the agent operates in |
|
|
||||||
| `--model <name>` | Override the model name |
|
|
||||||
| `--base-url <url>` | Override the OpenAI-compatible API base URL |
|
|
||||||
| `--api-key <key>` | API key for the model server |
|
|
||||||
| `--session-dir <path>` | Where saved sessions live |
|
|
||||||
| `--allow-write` | Allow file write/edit tools |
|
|
||||||
| `--allow-shell` | Allow shell execution |
|
|
||||||
| `--no-browser` | Don't auto-open a browser tab |
|
|
||||||
|
|
||||||
The GUI surfaces:
|
|
||||||
|
|
||||||
- multi-turn chat with tool-call cards (collapsible JSON args + results)
|
|
||||||
- saved sessions sidebar with one-click resume
|
|
||||||
- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`)
|
|
||||||
- live settings panel (model, base URL, working dir, permissions)
|
|
||||||
- usage / cost meta in the composer footer
|
|
||||||
|
|
||||||
> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 Session Persistence
|
|
||||||
|
|
||||||
Each `agent` run automatically saves a resumable session:
|
|
||||||
|
|
||||||
```text
|
|
||||||
session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
|
|
||||||
session_path=.port_sessions/agent/4f2c8c6f...
|
|
||||||
```
|
|
||||||
|
|
||||||
Resume a previous session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent-resume \
|
|
||||||
4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
|
|
||||||
"Continue the previous task and finish the missing parts."
|
|
||||||
```
|
|
||||||
|
|
||||||
Resume directly into interactive chat:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent-chat \
|
|
||||||
--resume-session-id <session-id> \
|
|
||||||
--cwd .
|
|
||||||
```
|
|
||||||
|
|
||||||
Inspect saved sessions:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ls -lt .port_sessions/agent
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 Testing
|
|
||||||
|
|
||||||
Run the full test suite:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m unittest discover -s tests -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Smoke tests:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m src.main agent "/help"
|
|
||||||
python3 -m src.main agent-context --cwd .
|
|
||||||
python3 -m src.main agent \
|
|
||||||
"Read src/agent_session.py and summarize the message flow." \
|
|
||||||
--cwd .
|
|
||||||
```
|
|
||||||
|
|
||||||
> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔐 Permission Model
|
|
||||||
|
|
||||||
Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
|
|
||||||
|
|
||||||
| Tier | Capability | Flag Required |
|
|
||||||
|------|-----------|---------------|
|
|
||||||
| **Read-only** | List, read, glob, grep | None (default) |
|
|
||||||
| **Write** | + file creation and editing | `--allow-write` |
|
|
||||||
| **Shell** | + shell command execution | `--allow-shell` |
|
|
||||||
| **Unsafe** | + destructive shell operations | `--unsafe` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔎 Parity Status
|
|
||||||
|
|
||||||
The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md).
|
|
||||||
|
|
||||||
It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚠️ Disclaimer
|
|
||||||
|
|
||||||
- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
|
|
||||||
- It does **not** ship the original npm source.
|
|
||||||
- It is **not** affiliated with or endorsed by Anthropic.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<sub>Built with 🐍 Python · Powered by 🐉 HarnessLab Team.</sub>
|
|
||||||
</p>
|
|
||||||
@@ -1,391 +0,0 @@
|
|||||||
中控数据Agent构建-汇报
|
|
||||||
Badcase 反馈渠道接入与自动收集分析:数据挖掘Agent设计方案
|
|
||||||
1. 背景与目标
|
|
||||||
- 数据开发是中控核心工作之一，但当前流程仍以人工驱动为主。
|
|
||||||
- 需求 / badcase 驱动的评测集构建、样本补充和线上挖掘链路分散，人工介入重、复用性差。
|
|
||||||
- 结合近期 AI native 工作方式转变，我们希望基于 Agent 底座先打通最小数据开发闭环。
|
|
||||||
当前方式的瓶颈与挑战：
|
|
||||||
- 人工驱动重：从需求、badcase 到评测集构建，多个关键环节依赖人工推进。
|
|
||||||
- 流程割裂重：人工构造、线上挖掘、LLM 生成彼此分散，数据格式转换和整理成本高。
|
|
||||||
- 经验复用弱：边界判断和处理经验难以沉淀，导致新问题进入后仍需重复劳动。
|
|
||||||
数据开发范式转变：
|
|
||||||
[图片]
|
|
||||||
2. AI Native数据Agent
|
|
||||||
不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。
|
|
||||||
让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。
|
|
||||||
|
|
||||||
---
|
|
||||||
2.1 设计目标与边界
|
|
||||||
- 核心目标：基于一个精简、可定制的 Agent 底座，建设一个面向中控数据开发场景的智能体执行底座。
|
|
||||||
- 方案形态：不是“流程自动化 + LLM 节点”，而是一个以 Agent 为核心、能够围绕任务自主检索、生成、筛选和整理的数据开发执行底座。
|
|
||||||
- 实现方式：基于 code-agent / claw-code-agent 实现，复用 Agent loop、文件读写、工具调用、代码执行、过程记录等通用能力。
|
|
||||||
[图片]
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2 核心架构
|
|
||||||
- 中控数据Agent应该由 6 个核心要素组成：
|
|
||||||
- Workspace：任务工作区
|
|
||||||
- Skills：领域经验包
|
|
||||||
- Tools：可执行工具
|
|
||||||
- Memory：Agent 外部认知状态
|
|
||||||
- Policy：权限与人工裁决边界
|
|
||||||
[图片]
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.1 Workspace：任务工作区
|
|
||||||
每个需求 / badcase 启动后，系统创建一个独立 workspace。
|
|
||||||
示例结构：
|
|
||||||
[图片]
|
|
||||||
Workspace 的作用：
|
|
||||||
- 承载任务上下文
|
|
||||||
- 记录 Agent 中间理解
|
|
||||||
- 保存探索过程
|
|
||||||
- 支持人机协作
|
|
||||||
- 沉淀可复用经验
|
|
||||||
- 保证过程可追溯
|
|
||||||
Agent 不是在一个固定流程里跑，而是在 workspace 按照我们之前的工作流程去工作
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.2 MD First：以 Markdown 作为 Agent 工作语言
|
|
||||||
[图片]
|
|
||||||
Agent 工作过程优先使用 Markdown
|
|
||||||
- MD 是 Agent 的工作语言；
|
|
||||||
- JSONL / CSV / DB 是数据资产的交换格式。
|
|
||||||
内容
|
|
||||||
推荐格式
|
|
||||||
需求理解
|
|
||||||
MD
|
|
||||||
边界分析
|
|
||||||
MD
|
|
||||||
人工裁决
|
|
||||||
MD
|
|
||||||
经验沉淀
|
|
||||||
MD
|
|
||||||
候选样本池
|
|
||||||
CSV / JSONL
|
|
||||||
评测集
|
|
||||||
JSONL
|
|
||||||
训练集
|
|
||||||
JSONL
|
|
||||||
回放结果
|
|
||||||
表格 + MD 报告
|
|
||||||
工具调用参数
|
|
||||||
schema / JSON
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.3 Skills：固化成熟工作流程
|
|
||||||
[图片]
|
|
||||||
Skill 是 Agent 可发现、可按需加载、可组合的领域经验包。
|
|
||||||
示例：
|
|
||||||
/skills/
|
|
||||||
router-label-boundary/
|
|
||||||
SKILL.md
|
|
||||||
examples.md
|
|
||||||
known-confusions.md
|
|
||||||
decision-principles.md
|
|
||||||
|
|
||||||
online-session-mining/
|
|
||||||
SKILL.md
|
|
||||||
query-patterns.md
|
|
||||||
sampling-strategies.md
|
|
||||||
badcase-mining.md
|
|
||||||
|
|
||||||
eval-set-construction/
|
|
||||||
SKILL.md
|
|
||||||
golden-set-rules.md
|
|
||||||
boundary-set-rules.md
|
|
||||||
anti-patterns.md
|
|
||||||
|
|
||||||
active-learning-router/
|
|
||||||
SKILL.md
|
|
||||||
disagreement-mining.md
|
|
||||||
hard-negative-mining.md
|
|
||||||
recall-gap-analysis.md
|
|
||||||
Agent 在运行中根据问题自主选择是否读取某个 skill。
|
|
||||||
例如：
|
|
||||||
发现 FAST_DIRECT 和 SLOW_FILTER_RANK 边界不清
|
|
||||||
→ 读取 router-label-boundary skill
|
|
||||||
|
|
||||||
需要从线上 session 挖相关样本
|
|
||||||
→ 读取 online-session-mining skill
|
|
||||||
|
|
||||||
发现模型离线准确率高但线上效果差
|
|
||||||
→ 读取 active-learning-router skill
|
|
||||||
Skill ：之前工作经验的沉淀
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.4 Tools：可执行能力
|
|
||||||
Tools 是 Agent 可以调用的实际能力。
|
|
||||||
示例：
|
|
||||||
search_online_sessions()
|
|
||||||
sample_top_queries()
|
|
||||||
find_similar_cases()
|
|
||||||
mine_by_pattern()
|
|
||||||
mine_by_embedding()
|
|
||||||
mine_by_model_disagreement()
|
|
||||||
cluster_and_dedup()
|
|
||||||
run_router_eval()
|
|
||||||
run_online_replay()
|
|
||||||
create_annotation_queue()
|
|
||||||
read_human_review_result()
|
|
||||||
train_router_model()
|
|
||||||
compare_model_versions()
|
|
||||||
Agent 不应该直接写复杂 SQL 或手工操作数据表。
|
|
||||||
系统应该提供稳定、可控、可审计的工具接口。
|
|
||||||
Agent 自己决定：
|
|
||||||
什么时候查线上 session
|
|
||||||
什么时候找历史裁决
|
|
||||||
什么时候跑模型分歧
|
|
||||||
什么时候构造混淆样本
|
|
||||||
什么时候创建标注任务
|
|
||||||
什么时候请求人工裁决
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.5 Memory：Agent 外部认知状态
|
|
||||||
Memory 不是简单存几个结构化字段。
|
|
||||||
错误理解：
|
|
||||||
{
|
|
||||||
"status": "running",
|
|
||||||
"target_label": "SLOW_FILTER_RANK"
|
|
||||||
}
|
|
||||||
正确理解：
|
|
||||||
Memory 是 Agent 为了完成长期任务而主动维护的外部认知状态。
|
|
||||||
建议形式：
|
|
||||||
memory/current_understanding.md
|
|
||||||
memory/open_questions.md
|
|
||||||
memory/human_decisions.md
|
|
||||||
memory/failed_attempts.md
|
|
||||||
memory/reusable_lessons.md
|
|
||||||
其中：
|
|
||||||
current_understanding.md
|
|
||||||
记录 Agent 当前对任务的理解。
|
|
||||||
open_questions.md
|
|
||||||
记录尚未解决的边界问题。
|
|
||||||
human_decisions.md
|
|
||||||
记录人工裁决及其理由。
|
|
||||||
failed_attempts.md
|
|
||||||
记录无效挖掘策略，避免重复踩坑。
|
|
||||||
reusable_lessons.md
|
|
||||||
记录可复用经验，供后续任务调用。
|
|
||||||
长期看，系统要沉淀：
|
|
||||||
哪些标签容易混淆
|
|
||||||
哪些边界已有裁决
|
|
||||||
哪些挖掘策略有效
|
|
||||||
哪些关键词误伤高
|
|
||||||
哪些样本适合评测集
|
|
||||||
哪些样本只适合训练集
|
|
||||||
哪些模型错误模式反复出现
|
|
||||||
|
|
||||||
---
|
|
||||||
2.2.6 Policy：权限与人工裁决边界
|
|
||||||
[图片]
|
|
||||||
Agent 可以自主推进任务，但不能无限自由。
|
|
||||||
需要明确哪些事情 Agent 可以自动做，哪些必须人类确认。
|
|
||||||
动作
|
|
||||||
权限
|
|
||||||
读取需求文档
|
|
||||||
自动
|
|
||||||
读取历史标签定义
|
|
||||||
自动
|
|
||||||
查询脱敏线上 session
|
|
||||||
自动
|
|
||||||
挖候选样本
|
|
||||||
自动
|
|
||||||
聚类去重
|
|
||||||
自动
|
|
||||||
预打标
|
|
||||||
自动
|
|
||||||
生成边界分析
|
|
||||||
自动
|
|
||||||
生成标签定义修订建议
|
|
||||||
自动
|
|
||||||
修改标签边界
|
|
||||||
人工确认
|
|
||||||
样本入库抽检
|
|
||||||
人工确认
|
|
||||||
修改历史数据资产
|
|
||||||
人工确认
|
|
||||||
|
|
||||||
---
|
|
||||||
2.3 典型运行方式
|
|
||||||
[图片]
|
|
||||||
|
|
||||||
用户输入：
|
|
||||||
一批 badcase + 需求说明 + 当前标签定义
|
|
||||||
Agent 启动任务 workspace。
|
|
||||||
然后 Agent 自主推进：
|
|
||||||
1. 读取需求和 badcase
|
|
||||||
2. 写 goal.md
|
|
||||||
3. 写 current_understanding.md
|
|
||||||
4. 检索相关标签定义
|
|
||||||
5. 检索历史类似裁决
|
|
||||||
6. 判断当前问题涉及哪些边界
|
|
||||||
7. 自主选择数据挖掘策略
|
|
||||||
8. 查询线上 session / topquery / 模型误判样本
|
|
||||||
9. 聚类、去重、找代表样本
|
|
||||||
10. 发现标签冲突或定义不清
|
|
||||||
11. 生成 open_questions.md
|
|
||||||
12. 向人提出高价值裁决问题
|
|
||||||
13. 根据裁决继续挖掘和修正
|
|
||||||
14. 生成候选评测集
|
|
||||||
15. 生成回放报告
|
|
||||||
16. 沉淀 reusable_lessons.md
|
|
||||||
|
|
||||||
---
|
|
||||||
3. 第一阶段目标
|
|
||||||
- 基于现有 Agent 底座完成最小运行环境搭建，并优先打通三条主要的数据开发链路：
|
|
||||||
- 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化
|
|
||||||
- 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化
|
|
||||||
- badcase 自动收集与分析链路打通
|
|
||||||
3.1 第一阶段落地方案
|
|
||||||
第一阶段基于现有 claw-code-agent 作为执行底座，在保留其通用 Agent 能力的基础上，补齐面向中控数据开发场景的输入、检索、生成、落盘和 review 能力。
|
|
||||||
让 claw-code-agent 从一个通用 code-agent，变成一个能够进入中控数据开发环境并执行真实任务的数据 Agent 底座。
|
|
||||||
前两周的目标：
|
|
||||||
在一个受控工作区内完成：
|
|
||||||
- 读取需求 / badcase
|
|
||||||
- 检索线上样本
|
|
||||||
- 生成或筛选评测集候选
|
|
||||||
- 记录过程和中间判断
|
|
||||||
- 输出可落盘、可 review 的结果
|
|
||||||
在这一底座之上，第一阶段优先验证三条真实链路：
|
|
||||||
- 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化
|
|
||||||
- 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化
|
|
||||||
- badcase 自动收集与分析链路打通
|
|
||||||
落地原则：
|
|
||||||
底层复用
|
|
||||||
claw-code-agent 现有的 loop、tool calling、session persistence、transcript、compaction、markdown memory 注入、policy hook 等能力已经足够成熟，适合作为底层执行引擎直接复用。
|
|
||||||
因此，第一阶段不重写主循环，不重写工具调用链，不重写 session 基础设施。
|
|
||||||
上层收口
|
|
||||||
当前 claw-code-agent 的默认形态是 coding-first：prompt 偏代码助手，工具面偏泛代码操作，workspace 也更接近 code workspace。
|
|
||||||
第一阶段要做的不是扩展更多能力，而是把这些默认形态收口成 data-first：让 Agent 更聚焦于数据检索、样本筛选、评测集构建和结果沉淀。
|
|
||||||
具体任务拆解：
|
|
||||||
直接复用底层执行内核
|
|
||||||
这一部分不作为改造重点，只作为底座能力直接承接：
|
|
||||||
- Agent loop
|
|
||||||
- session / transcript / file_history
|
|
||||||
- tool schema + tool execution
|
|
||||||
- markdown memory 注入基础能力
|
|
||||||
- hook / policy 基础机制
|
|
||||||
- compaction / replay 基础设施
|
|
||||||
这些能力已经能支撑“模型驱动循环 + 工具调用 + 过程追踪”，第一阶段不需要投入主要精力。
|
|
||||||
需要改造的四个点：
|
|
||||||
1）把 code workspace 改成 task workspace @王云浩
|
|
||||||
这是最关键的一步。
|
|
||||||
当前底座支持 markdown memory，但还没有真正 task-native 的工作区。第一阶段要把任务固定到 /tasks/{task_id}/ 目录下，让输入、记忆、产物和日志都围绕任务目录组织。
|
|
||||||
2）把 coding-first prompt 改成 data-first prompt @王云浩
|
|
||||||
当前 system prompt 更强调读代码、改代码、bash、git、验证代码修改。
|
|
||||||
第一阶段需要改成围绕：
|
|
||||||
- 需求理解
|
|
||||||
- 边界分析
|
|
||||||
- open questions
|
|
||||||
- 样本挖掘
|
|
||||||
- 标注 / 裁决
|
|
||||||
- eval/train set 构造
|
|
||||||
- 经验沉淀
|
|
||||||
这些数据任务来组织默认口径。
|
|
||||||
3）把默认工具集改成最小数据工具集 @武阳
|
|
||||||
当前工具面过宽，对数据 Agent 初版来说不是增强，而是噪音。
|
|
||||||
第一阶段要做的是裁出一套 default_data_tool_registry()，只保留必要文件工具和少量数据专用工具，让 Agent 的动作空间收敛。
|
|
||||||
4）把 coding policy 扩展成数据治理 policy @武阳
|
|
||||||
当前权限语义更像：
|
|
||||||
- allow write
|
|
||||||
- allow shell
|
|
||||||
- deny tool
|
|
||||||
- ask user
|
|
||||||
但数据场景需要更细的治理边界，比如：
|
|
||||||
- 是否允许查线上样本
|
|
||||||
- 是否允许导出敏感字段
|
|
||||||
- 是否允许生成标注任务
|
|
||||||
- 哪些问题必须人工裁决
|
|
||||||
- 哪些标签修订必须人工确认
|
|
||||||
这一部分必须在第一阶段明确下来。
|
|
||||||
需要重点建设的两层能力：
|
|
||||||
1）之前挖掘经验通过SKILL的方式进行注入(需要进行实验和验证)
|
|
||||||
第一阶段 skill 不应再只是 prompt 片段，而应沉淀成目录化 markdown 经验包，至少覆盖：
|
|
||||||
- 边界判断
|
|
||||||
- 线上挖掘
|
|
||||||
- 评测集构建
|
|
||||||
并采用“元信息先注入，正文按需展开”的方式，避免一次性把全部经验塞进上下文。
|
|
||||||
2）artifacts 统一沉淀
|
|
||||||
第一阶段所有关键结果都应统一沉淀到 task workspace 下，而不是只停留在 session json 或临时输出里。
|
|
||||||
这一步是后续 review、复盘、数据资产化的前提。
|
|
||||||
目标的形态
|
|
||||||
/tasks/{task_id}/
|
|
||||||
goal.md
|
|
||||||
context/
|
|
||||||
requirement.md
|
|
||||||
badcase.md
|
|
||||||
memory/
|
|
||||||
open_questions.md
|
|
||||||
working_notes.md
|
|
||||||
decisions.md
|
|
||||||
artifacts/
|
|
||||||
eval_candidates.jsonl
|
|
||||||
mining_strategy.md
|
|
||||||
report.md
|
|
||||||
logs/
|
|
||||||
agent_trace.md
|
|
||||||
在这个形态下，Agent 能够围绕一个任务完成：
|
|
||||||
- 输入读取
|
|
||||||
- 数据检索
|
|
||||||
- 样本筛选或生成
|
|
||||||
- 结果沉淀
|
|
||||||
- 人工 review 触发
|
|
||||||
代码改造清单
|
|
||||||
类型
|
|
||||||
项目
|
|
||||||
第一阶段动作
|
|
||||||
说明
|
|
||||||
直接复用
|
|
||||||
Agent loop
|
|
||||||
保留
|
|
||||||
不重写主循环
|
|
||||||
直接复用
|
|
||||||
session / transcript / compaction
|
|
||||||
保留
|
|
||||||
直接复用过程追踪能力
|
|
||||||
直接复用
|
|
||||||
tool schema / execution
|
|
||||||
保留
|
|
||||||
不改调用链
|
|
||||||
核心改造
|
|
||||||
workspace
|
|
||||||
改造
|
|
||||||
从 code workspace 收口为 task workspace
|
|
||||||
核心改造
|
|
||||||
system prompt
|
|
||||||
改造
|
|
||||||
从 coding-first 改为 data-first
|
|
||||||
核心改造
|
|
||||||
默认工具集
|
|
||||||
改造
|
|
||||||
裁出最小数据工具集
|
|
||||||
核心改造
|
|
||||||
policy / human gate
|
|
||||||
改造
|
|
||||||
从 coding 权限扩展为数据治理边界
|
|
||||||
必须新增
|
|
||||||
skill 机制
|
|
||||||
新增
|
|
||||||
目录化 markdown 经验包，按需加载
|
|
||||||
必须新增
|
|
||||||
artifacts 沉淀规则
|
|
||||||
新增
|
|
||||||
所有关键结果统一沉淀到 task 目录
|
|
||||||
业务验证
|
|
||||||
生成式评测集构建
|
|
||||||
打通
|
|
||||||
作为第一条真实链路
|
|
||||||
业务验证
|
|
||||||
线上问题挖掘
|
|
||||||
打通
|
|
||||||
作为第二条真实链路
|
|
||||||
业务验证
|
|
||||||
badcase 自动收集分析
|
|
||||||
打通
|
|
||||||
作为第三条真实链路
|
|
||||||
[图片]
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user