claude-code-advisor
Advanced tools
claude-code-advisor - npm Package Compare versions
+30
-61
@@ -8,3 +8,3 @@ --- | ||
| You are an expert advisor specializing in Claude Code's internal architecture, design patterns, and Mitsein-specific adaptation decisions. Your knowledge is grounded in source-level evidence from Claude Code's 1,900+ TypeScript files. | ||
| You are an expert advisor specializing in Claude Code's internal architecture and design patterns. Your knowledge is grounded in source-level evidence from Claude Code's 1,900+ TypeScript files. | ||
@@ -37,3 +37,3 @@ ## Core Knowledge Areas | ||
| 8. **Depth tracking is advisory, not enforced in CC.** Claude Code has no hard recursion limit — only a boilerplate check. OpenClaw uses depth-based role model (main → orchestrator → leaf). Mitsein has `max_spawn_depth: 1` but only on spawn, not delegate. | ||
| 8. **Depth tracking is advisory, not enforced.** Claude Code has no hard recursion limit — only a boilerplate check. Design orchestration layers to enforce their own depth limits. | ||
@@ -66,32 +66,2 @@ ## Quick Reference | ||
| ## Mitsein-Specific Guidance | ||
| When advising on Mitsein (the AI orchestration platform being built on top of Claude Code): | ||
| **Architecture gap to fix:** | ||
| - `sys_delegate_agent` creates DB thread but never starts an agent run — needs internal HTTP call to API service (`POST /thread/{id}/agent/start`) | ||
| - `kill_all()` must be called in `run_loop` finally block to prevent orphaned asyncio Tasks | ||
| - Depth enforcement must apply to `delegate` tool, not just `spawn` | ||
| **SubagentTracker** unifies spawn (asyncio.Task) and delegate (DB-backed) agents under a single state model. Uniform status enum: `pending | running | completed | failed | killed`. Maps to CC's `LocalAgentTaskState` pattern. | ||
| **NotificationWriter** handles push-based completion for delegate agents. Uses system-role messages injected into the parent thread. Add `ON CONFLICT DO NOTHING` for idempotency — delegate completions can arrive multiple times due to retry. | ||
| **`kill_all()` return signature:** `(count: int, cancelled_tasks: List[asyncio.Task])`. Callers must `await asyncio.gather(*tasks, return_exceptions=True)` — not fire-and-forget. | ||
| **Token budget** uses a sliding window deque. Don't use a simple counter — deque allows eviction of old windows and accurate per-window accounting. | ||
| **Atomic agent run pick-up:** | ||
| ```sql | ||
| UPDATE agent_runs | ||
| SET status = 'running', claimed_by = $worker_id, started_at = NOW() | ||
| WHERE id = $run_id AND claimed_by IS NULL | ||
| RETURNING * | ||
| -- Use FOR UPDATE SKIP LOCKED at queue-scan level | ||
| ``` | ||
| **Context forwarding strategy:** Skip full fork (DB-backed context, not JSONL). For spawn: pass a concise "mission brief". For delegate: write parent context summary as first message. Full context copy only if explicitly needed. | ||
| **What Mitsein has that CC doesn't:** Hook engine for lifecycle events (SUBAGENT_START/STOP), DB-backed persistent threads (survives restarts, real-time collab), hybrid YAML+DB agent config, memex/diary cross-agent context. | ||
| ## Available Documentation | ||
@@ -103,32 +73,31 @@ | ||
| |------|----------| | ||
| | `00-feature-discovery.md` | Feature flags (248), agent tools (57), slash commands (103+), hidden systems (11) — master index | | ||
| | `00-feature-discovery.md` | Feature flags (87 build-time, 59 GrowthBook), agent tools (57), slash commands (103+), hidden systems — master index | | ||
| | `01-agent-spawning.md` | AgentTool 5-way dispatch, CacheSafeParams, LocalAgentTaskState, spawn-to-completion flow | | ||
| | `02-tool-system.md` | Tool registry, permission model, tool schemas, built-in vs MCP tools | | ||
| | `03-memory.md` | Memory types (user/project/local), CLAUDE.md loading, memory scopes | | ||
| | `02-tool-system.md` | Tool<Input,Output,Progress> interface, buildTool() factory, StreamingToolExecutor concurrency, 5-stage permission pipeline | | ||
| | `03-memory.md` | Memory types, CLAUDE.md loading chain, findRelevantMemories, Auto-Dream trigger conditions | | ||
| | `04-hook-engine.md` | 23 hook events, 5 hook types, execution lifecycle, pattern matching, async hooks | | ||
| | `05-context-compression.md` | Context window management, compaction strategies, token budget | | ||
| | `06-skill-system.md` | Skill loading (6 sources), frontmatter schema, bundled skills, MCP skills | | ||
| | `07-permission-model.md` | Trust levels, permission modes, deny rules, tool allowlists | | ||
| | `08-config-system.md` | Config scopes, settings.json format, env vars, feature flags | | ||
| | `09-streaming.md` | SSE streaming, token counting, progress updates, streaming tool calls | | ||
| | `10-session.md` | Session transcript (JSONL), resume flow, bootstrap state, crash recovery | | ||
| | `11-agent-communication.md` | SendMessage, message queue, parent-child communication, notification delivery | | ||
| | `12-memory-dataflow.md` | Memory read/write flow, extraction hooks, Auto-Dream, diary system | | ||
| | `13-query-loop.md` | Main query loop, tool execution cycle, turn lifecycle | | ||
| | `14-bridge-system.md` | Bridge/remote session, Teleport, cross-machine context transfer | | ||
| | `15-ink-terminal-ui.md` | Ink React rendering, terminal UI components, spinner states | | ||
| | `16-task-system.md` | Task (Todo) system, TodoWrite/Read tools, task persistence | | ||
| | `17-system-prompt.md` | System prompt assembly, CLAUDE.md injection, agent prompt variants | | ||
| | `18-mcp-lifecycle.md` | MCP config scopes (7), transports (6), connection flow, tool discovery | | ||
| | `19-e2e-request-flow.md` | End-to-end request flow from user input to API response to tool execution | | ||
| | `20-cost-tracking.md` | Token cost tracking, model usage metrics, per-turn accounting | | ||
| | `21-agent-definition.md` | Agent .md format, built-in agents (6), selection pipeline, override priority | | ||
| | `22-testing-practices.md` | Claude Code testing patterns, test utilities, mock strategies | | ||
| | `23-command-system.md` | Slash command system, command discovery, custom commands | | ||
| | `24-plugin-architecture.md` | Plugin system, plugin MCP servers, plugin skill loading | | ||
| | `25-remote-sessions.md` | CCR (remote) session management, UltraPlan, remote agent lifecycle | | ||
| | `26-swarm-coordinator.md` | Coordinator mode, worker agents, task-notification XML protocol | | ||
| | `27-voice-mode.md` | Voice input processing, audio transcription integration | | ||
| | `28-keybindings-vim.md` | Vim mode, keybinding customization, input handling | | ||
| | `29-lsp-diagnostics.md` | LSP integration, diagnostics feed, code intelligence | | ||
| | `30-agent-communication-design.md` | **Mitsein deep-dive**: 4-expert design discussion comparing Mitsein/OpenClaw/CC agent architectures, 4-phase implementation roadmap, concrete code patterns for SubagentTracker, NotificationWriter, kill_all(), abort cascade | | ||
| | `05-context-compression.md` | Autocompact thresholds, microcompact, POST_COMPACT constants, token budget | | ||
| | `06-skill-system.md` | Skill loading (6 sources), frontmatter schema (16 fields), bundled skills, MCP skills | | ||
| | `07-permission-model.md` | Permission modes, denial tracking, rule sources, trust levels | | ||
| | `08-config-system.md` | SETTING_SOURCES priority, settings.json paths, MDM policy, 3-layer cache | | ||
| | `09-streaming.md` | queryModelWithStreaming, withRetry (10 retries), FOREGROUND_529_RETRY_SOURCES, progress types | | ||
| | `10-session.md` | JSONL transcript paths, size limits (50MB), bootstrap state, session resume | | ||
| | `11-agent-communication.md` | Sync/async agent patterns, enqueueAgentNotification, runAsyncAgentLifecycle, message queue | | ||
| | `12-memory-dataflow.md` | 3 write channels, static+dynamic read layers, extraction, Auto-Dream pipeline | | ||
| | `13-query-loop.md` | 6-phase main loop, QueryEngine, feature gates, context assembly, recovery paths | | ||
| | `14-bridge-system.md` | Bridge API (8 endpoints), SpawnMode, trusted device, BoundedUUIDSet | | ||
| | `15-ink-terminal-ui.md` | Ink double-buffering, terminal capability detection, hit-test, selection state machine | | ||
| | `16-task-system.md` | 7 TaskType variants, TaskStateBase, ID prefixes, disk output, UI footer | | ||
| | `17-system-prompt.md` | getSystemPrompt(), 7 static sections, dynamic registry, CLAUDE.md discovery chain | | ||
| | `18-mcp-lifecycle.md` | 7 config scopes, 6 transports, connectToServer() flow, fetchToolsForClient, elicitation | | ||
| | `19-e2e-request-flow.md` | 8-phase trace: bootstrap → query → tool execution → response | | ||
| | `20-cost-tracking.md` | calculateUSDCost, ModelUsage, hard budget check, session persistence | | ||
| | `21-agent-definition.md` | AgentDefinition union, built-in agents (6), filter pipeline, override priority | | ||
| | `22-testing-practices.md` | _resetForTesting pattern, VCR fixtures, DI patterns, TEST_GLOBAL_CONFIG | | ||
| | `23-command-system.md` | loadAllCommands 7-source pipeline, feature-gated commands, REMOTE_SAFE_COMMANDS | | ||
| | `24-plugin-architecture.md` | assemblePluginLoadResult, verifyAndDemote, cache-only startup, background install | | ||
| | `25-remote-sessions.md` | SessionsWebSocket reconnect/close codes, CCR vs Direct Connect, ping intervals | | ||
| | `26-swarm-coordinator.md` | Coordinator mode, TeamCreate/TeamDelete lifecycle, backend dispatch | | ||
| | `27-voice-mode.md` | voice_stream WebSocket, OAuth gate, keepalive (8s), hold-to-talk | | ||
| | `28-keybindings-vim.md` | resolveKeyWithChordState, Vim state machine (10 states), chord resolver | | ||
| | `29-lsp-diagnostics.md` | LSPTool operations (9), passive diagnostics pipeline, formatDiagnosticsForAttachment | |
@@ -191,3 +191,3 @@ # 11. Agent Communication | ||
| | Mechanism | Claude Code | | ||
| | Mechanism | Implementation | | ||
| |---|---| | ||
@@ -194,0 +194,0 @@ | Sync spawn (blocking) | async generator | |
@@ -135,23 +135,2 @@ # 22. Testing Infrastructure & Inferred Practices | ||
| ## Practice 5: The "Don't Mock the Database" Observation | ||
| ``` | ||
| // memoryTypes.ts:65-66 (within memory taxonomy example text): | ||
| // "don't mock the database in these tests — | ||
| // we got burned last quarter when mocked tests | ||
| // passed but prod migration failed" | ||
| // What this confirms: | ||
| // 1. This perspective was explicitly encoded in system prompt / memory content | ||
| // 2. The team considered it worth propagating as institutional knowledge | ||
| // What this does NOT confirm: | ||
| // - "all DB tests use real databases" | ||
| // - "this is a hard rule in the current test suite" | ||
| ``` | ||
| This is a team lesson written into system knowledge, not a directly provable test policy from the snapshot. | ||
| --- | ||
| ## Practice 6: Permission-Dedicated Test Tool | ||
@@ -158,0 +137,0 @@ |
@@ -59,13 +59,2 @@ # 26. Swarm / Teams / Coordinator | ||
| ## Scope Relative to Other Agent Systems | ||
| | System | Concern | | ||
| |---|---| | ||
| | `01-agent-spawning` | Generic subagent fork/spawn | | ||
| | `11-agent-communication` | Message passback | | ||
| | `16-task-system` | Task management | | ||
| | **Swarm/Teams** | Leader identity, team files, backend selection, cleanup rules | | ||
| Swarm/Teams is the layer where Claude Code moves from multi-agent to multi-worker orchestration with explicit organizational structure. | ||
| **Tags:** swarm, team lifecycle, coordinator mode, in-process backend |
+1
-1
| { | ||
| "name": "claude-code-advisor", | ||
| "version": "1.1.0", | ||
| "version": "1.2.0", | ||
| "description": "Claude Code Advisor — distilled architecture docs + agent/skill for building on top of Claude Code", | ||
@@ -5,0 +5,0 @@ "bin": { |
+21
-34
| --- | ||
| name: claude-code-advisor | ||
| description: Invoke the Claude Code Advisor agent for architectural guidance on Claude Code patterns, agent design, MCP, hooks, and Mitsein-specific decisions. | ||
| description: Invoke the Claude Code Advisor agent for architectural guidance on Claude Code patterns, agent design, MCP, hooks, and system design decisions. | ||
| agent: claude-code-advisor | ||
@@ -19,31 +19,30 @@ --- | ||
| | `01-agent-spawning.md` | AgentTool 5-way dispatch, CacheSafeParams fork optimization, LocalAgentTaskState lifecycle | | ||
| | `02-tool-system.md` | Tool registry, permission model, built-in vs MCP tools, tool schemas | | ||
| | `03-memory.md` | Memory types (user/project/local), CLAUDE.md loading, memory scopes | | ||
| | `02-tool-system.md` | Tool registry, permission pipeline, built-in vs MCP tools, StreamingToolExecutor | | ||
| | `03-memory.md` | Memory types (user/project/local), CLAUDE.md loading, Auto-Dream | | ||
| | `04-hook-engine.md` | 23 hook events, 5 hook types, pattern matching, async hooks, output schema | | ||
| | `05-context-compression.md` | Context window management, compaction, token budget sliding window | | ||
| | `05-context-compression.md` | Context window management, compaction strategies, token budget | | ||
| | `06-skill-system.md` | Skill loading (6 sources), frontmatter schema (16 fields), bundled/MCP skills | | ||
| | `07-permission-model.md` | Trust levels, permission modes, deny rules, tool allowlists | | ||
| | `07-permission-model.md` | Permission modes, denial tracking, rule sources, trust levels | | ||
| | `08-config-system.md` | Config scopes, settings.json, env vars, feature flags | | ||
| | `09-streaming.md` | SSE streaming, token counting, progress updates | | ||
| | `09-streaming.md` | SSE streaming, retry logic, progress updates | | ||
| | `10-session.md` | Session transcript (JSONL), resume flow, bootstrap state, crash recovery | | ||
| | `11-agent-communication.md` | SendMessage, message queue priority, parent-child notification delivery | | ||
| | `12-memory-dataflow.md` | Memory extraction hooks, Auto-Dream, diary system, cross-agent context | | ||
| | `13-query-loop.md` | Main query loop, tool execution cycle, turn lifecycle | | ||
| | `11-agent-communication.md` | Message queue, parent-child notification delivery, async agent lifecycle | | ||
| | `12-memory-dataflow.md` | Memory extraction hooks, Auto-Dream, diary system | | ||
| | `13-query-loop.md` | Main query loop (6 phases), tool execution cycle, turn lifecycle | | ||
| | `14-bridge-system.md` | Bridge/remote sessions, Teleport, cross-machine context transfer | | ||
| | `15-ink-terminal-ui.md` | Ink React rendering, terminal UI components | | ||
| | `16-task-system.md` | Task (Todo) system, TodoWrite/Read tools, task persistence | | ||
| | `17-system-prompt.md` | System prompt assembly, CLAUDE.md injection, agent prompt variants | | ||
| | `15-ink-terminal-ui.md` | Ink React rendering, terminal UI, double-buffering | | ||
| | `16-task-system.md` | 7 TaskType variants, lifecycle management, disk output | | ||
| | `17-system-prompt.md` | System prompt assembly, CLAUDE.md injection, dynamic registry | | ||
| | `18-mcp-lifecycle.md` | MCP config scopes (7), transports (6), connection flow, tool discovery | | ||
| | `19-e2e-request-flow.md` | End-to-end: user input → API → tool execution → response | | ||
| | `20-cost-tracking.md` | Token cost tracking, model usage metrics, per-turn accounting | | ||
| | `21-agent-definition.md` | Agent .md format, built-in agents, selection/filter pipeline, override priority | | ||
| | `22-testing-practices.md` | Claude Code testing patterns, test utilities, mock strategies | | ||
| | `23-command-system.md` | Slash command system, command discovery, custom commands | | ||
| | `24-plugin-architecture.md` | Plugin system, plugin MCP servers, plugin skill loading | | ||
| | `25-remote-sessions.md` | CCR remote session management, UltraPlan, remote agent lifecycle | | ||
| | `20-cost-tracking.md` | Token cost tracking, model usage metrics, budget enforcement | | ||
| | `21-agent-definition.md` | Agent .md format, built-in agents (6), selection pipeline, override priority | | ||
| | `22-testing-practices.md` | Claude Code testing patterns, VCR fixtures, _resetForTesting, mock strategies | | ||
| | `23-command-system.md` | Slash command system, 7-source load pipeline, feature-gated commands | | ||
| | `24-plugin-architecture.md` | Plugin system, plugin MCP servers, background marketplace install | | ||
| | `25-remote-sessions.md` | CCR remote session management, UltraPlan, reconnect semantics | | ||
| | `26-swarm-coordinator.md` | Coordinator mode, worker agents, task-notification XML protocol | | ||
| | `27-voice-mode.md` | Voice input processing, audio transcription integration | | ||
| | `28-keybindings-vim.md` | Vim mode, keybinding customization | | ||
| | `29-lsp-diagnostics.md` | LSP integration, diagnostics feed, code intelligence | | ||
| | `30-agent-communication-design.md` | **Mitsein deep-dive**: 4-expert multi-system comparison, 4-phase roadmap, SubagentTracker, NotificationWriter, kill_all(), abort cascade patterns | | ||
| | `27-voice-mode.md` | Voice input, WebSocket protocol, OAuth gate | | ||
| | `28-keybindings-vim.md` | Vim mode, chord resolver, keybinding customization | | ||
| | `29-lsp-diagnostics.md` | LSP integration, diagnostics pipeline, code intelligence | | ||
@@ -59,14 +58,2 @@ ## Usage | ||
| - **Skill and agent definition authoring** — frontmatter fields, override priority, MCP requirements filtering | ||
| - **Mitsein subagent system design** — SubagentTracker, NotificationWriter, delegate wiring, kill_all(), orphan prevention | ||
| - **Cross-agent communication patterns** — message queue, task-notification XML, push vs pull notification | ||
| ## Mitsein Quick Reference | ||
| Key decisions from `30-agent-communication-design.md`: | ||
| - **SubagentTracker** unifies spawn (asyncio.Task) and delegate (DB-backed) agents | ||
| - **NotificationWriter** uses system-role messages with `ON CONFLICT DO NOTHING` for idempotency | ||
| - **`kill_all()`** returns `(count, cancelled_tasks)` — callers must `await asyncio.gather(*tasks)` | ||
| - **Token budget** uses sliding window deque, not a simple counter | ||
| - **Atomic agent run pick-up**: `UPDATE WHERE claimed_by IS NULL RETURNING *` + `FOR UPDATE SKIP LOCKED` | ||
| - **Context forwarding**: skip full fork for DB-backed context; use structured "mission brief" instead |
No alert changes
Worsened metrics
- Total package byte prevSize
252833
-1.54%No dependency changes