185 lines
15 KiB
Markdown
185 lines
15 KiB
Markdown
# Claude Code Source Analysis — Strategic Relevance to Waggle OS
|
|
|
|
**Date:** 2026-04-01
|
|
**Analyst:** Cowork Session (CxO Advisory)
|
|
**Scope:** Claude Code source (`D:\Projects\Claude Code Source\src\src`), cross-referenced with `open-multi-agent` and `claw-code` repositories
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
The Claude Code source is the most strategically valuable reference material for Waggle OS — far more than either open-source repository analyzed previously. It is the production-grade implementation of the exact system architecture Waggle aspires to: multi-agent orchestration, persistent memory, tool harness, MCP integration, skills framework, and session management. This is not a competitor to study — it is the reference implementation of the patterns Waggle needs to mature.
|
|
|
|
**Verdict:** HIGH strategic value as an architectural reference. Not for code adoption (IP risk), but for pattern extraction, gap identification, and design validation.
|
|
|
|
---
|
|
|
|
## Architecture Breakdown (What Matters for Waggle)
|
|
|
|
### 1. Agent System — The Core Differentiator
|
|
|
|
**Claude Code's approach:**
|
|
- **AgentTool** is the central orchestration primitive. Every agent spawn goes through a single `buildTool()` call with Zod-validated input/output schemas.
|
|
- **Built-in agent types** are defined as simple TypeScript definitions (not full classes): `generalPurposeAgent`, `exploreAgent`, `planAgent`, `verificationAgent`, `claudeCodeGuideAgent`, `statuslineSetup`. Each specifies: `agentType`, `whenToUse`, `tools` (allowlist), `disallowedTools` (denylist), and optional `model` override.
|
|
- **Custom agents** loaded from user-defined directories via `loadAgentsDir.ts` — file-based agent definitions alongside built-in ones.
|
|
- **Agent lifecycle:** spawn → run (with own tool pool) → return result to parent. No persistent state between spawns. Each agent gets a fresh conversation context unless it's a "fork" (inherits parent context).- **Fork subagent pattern** (feature-gated): allows spawning a clone of the current agent that inherits the full conversation context. Designed for research tasks where the parent wants the answer without polluting its own context with intermediate tool calls.
|
|
- **Coordinator mode** (feature-gated): a special operating mode where the orchestrating agent has a restricted tool set (`COORDINATOR_MODE_ALLOWED_TOOLS`) and delegates all execution to subagents.
|
|
- **Agent Swarms / Teammates** (feature-gated): multi-agent collaboration using tmux sessions. Spawns real processes that can communicate via `SendMessageTool`.
|
|
|
|
**Waggle gap analysis:**
|
|
- Waggle has 13 agent personas but lacks the structured agent definition format (tools allowlist/denylist per agent type).
|
|
- Waggle lacks the fork pattern — critical for research-heavy workflows where context inheritance saves tokens.
|
|
- Waggle lacks coordinator mode — the pattern where a "master" agent only delegates, never executes directly.
|
|
- Waggle lacks the SendMessage inter-agent communication primitive.
|
|
- Waggle's agent spawning appears monolithic vs. Claude Code's composable tool-pool assembly.
|
|
|
|
**Recommendation:** Adopt the agent definition schema (type + tools + whenToUse + model) as Waggle's standard. Implement coordinator mode for Mission Control. The fork pattern maps directly to Waggle Dance's workflow orchestration needs.
|
|
|
|
---
|
|
|
|
### 2. Memory System — The Competitive Moat
|
|
|
|
**Claude Code's approach:**
|
|
- **File-based memory** with YAML frontmatter: each memory is a markdown file with `name`, `description`, `type` fields.
|
|
- **Four-type taxonomy:** `user` (role/preferences), `feedback` (behavioral corrections), `project` (ongoing work context), `reference` (pointers to external systems).
|
|
- **MEMORY.md as index:** a single entrypoint file (max 200 lines, 25KB) that serves as a table of contents. Individual memories are separate files.
|
|
- **Relevance filtering via side-query:** `findRelevantMemories.ts` uses a lightweight Sonnet call to select which memory files are relevant to the current user query. Scans frontmatter headers, sends them to Sonnet with the query, gets back up to 5 relevant filenames. This is NOT keyword matching — it's semantic relevance via LLM.
|
|
- **Memory scan:** `memoryScan.ts` reads frontmatter from all memory files without loading full content. Only selected files get fully loaded.
|
|
- **Team memory** (feature-gated): shared memory across team members with separate paths.
|
|
- **Stale memory handling:** memories include creation timestamps; the system warns about potentially outdated information.
|
|
**Waggle gap analysis:**
|
|
- Waggle uses a graph database for memory — architecturally more sophisticated than flat files. However, the graph structure may be over-engineered for what Claude Code proves works: simple frontmatter-indexed files with LLM-powered relevance filtering.
|
|
- Waggle lacks the four-type memory taxonomy. This is a proven classification that prevents memory bloat (code patterns, git history, etc. are explicitly excluded).
|
|
- Waggle lacks the "side-query" relevance pattern — using a lightweight model to pre-filter context before injecting into the main conversation.
|
|
- Waggle lacks the explicit "what NOT to save" guardrails that prevent the memory system from becoming a dumping ground.
|
|
|
|
**Recommendation:** The graph DB is fine for storage, but adopt the four-type taxonomy as the schema layer on top. The side-query relevance pattern is immediately valuable — it's how Claude Code keeps memory injection surgical rather than flooding context.
|
|
|
|
---
|
|
|
|
### 3. Tool Harness — The Execution Layer
|
|
|
|
**Claude Code's approach:**
|
|
- **`buildTool()` factory:** every tool (Bash, FileRead, FileWrite, Grep, Glob, Agent, etc.) is constructed via a standardized factory with: `name`, `description`, `inputSchema` (Zod), `outputSchema` (Zod), `isEnabled()`, `call()`, and React-based UI components for rendering.
|
|
- **Tool pool assembly:** `assembleToolPool()` dynamically constructs the available tool set per agent, respecting allowlists, denylists, MCP tools, and feature gates.
|
|
- **MCP integration:** full Model Context Protocol client with `MCPConnectionManager`, OAuth support, channel permissions, and server approval flows.
|
|
- **Skill system:** skills are loaded from directories (`loadSkillsDir.ts`) and converted into tool-like invocations via `SkillTool`. Skills can come from bundled sources, user directories, or MCP servers.
|
|
- **Permission system:** granular per-tool permissions with `canUseTool` checks, auto-mode denials, and classifier-based approvals.
|
|
- **ToolSearch:** deferred tool loading — tools are registered by name but their full schema is only fetched when needed, reducing prompt size.
|
|
**Waggle gap analysis:**
|
|
- Waggle has tool execution but lacks the standardized `buildTool()` pattern with schema validation.
|
|
- Waggle's MCP integration appears less mature than Claude Code's full connection manager with OAuth.
|
|
- Waggle lacks deferred tool loading (ToolSearch pattern) — critical for managing prompt size when connectors scale.
|
|
- Waggle lacks the per-agent tool pool customization.
|
|
|
|
**Recommendation:** The `buildTool()` pattern and `assembleToolPool()` composition model should be Waggle's target architecture for tool management. Deferred tool loading via ToolSearch is essential as Waggle's connector count grows beyond 32.
|
|
|
|
---
|
|
|
|
### 4. QueryEngine — The Brain
|
|
|
|
**Claude Code's approach:**
|
|
- **QueryEngine class:** owns the entire conversation lifecycle. One instance per conversation, persists state across turns.
|
|
- **System prompt assembly:** modular, with sections from memory, CLAUDE.md files, skills, MCP servers, and environment details — all composable.
|
|
- **Token budget management:** `tokenBudget.ts` manages context window allocation across system prompt, history, and tool results.
|
|
- **Context analysis:** determines what context to inject based on the current query.
|
|
- **Compact/snip:** conversation history compression when context fills up — maintains coherence while discarding intermediate noise.
|
|
- **File state cache:** tracks which files have been read, preventing redundant fetches.
|
|
- **Cost tracking:** per-session token counting and cost estimation.
|
|
|
|
**Waggle gap analysis:**
|
|
- Waggle has a chat interface but likely lacks the token budget management sophistication.
|
|
- The system prompt assembly pattern (composable sections) is exactly what Waggle needs for its multi-workspace, multi-agent architecture.
|
|
- History compression (snip/compact) is essential for long sessions — Waggle will hit context limits with 13 agents generating output.
|
|
|
|
**Recommendation:** Study the QueryEngine pattern closely. The token budget management and history compression are non-negotiable for production quality.
|
|
---
|
|
|
|
### 5. Session & Task Management
|
|
|
|
**Claude Code's approach:**
|
|
- **Four task types:** `LocalAgentTask` (foreground subagent), `RemoteAgentTask` (remote sandbox), `InProcessTeammateTask` (tmux-spawned teammate), `DreamTask` (background processing).
|
|
- **Progress tracking:** agents report progress via `AgentToolProgress` events. Parents can monitor without polling.
|
|
- **Background execution:** agents can run in background with automatic notification on completion.
|
|
- **Session persistence:** transcripts recorded to disk, sessions resumable across restarts.
|
|
- **Worktree isolation:** agents can operate in git worktrees for safe experimentation.
|
|
|
|
**Waggle gap analysis:**
|
|
- Waggle's Cockpit view tracks agent status but appears to lack structured task types.
|
|
- Background execution with notification is a UX pattern Waggle should adopt for long-running agent workflows.
|
|
- Session persistence and resume capability is critical for the desktop app use case.
|
|
|
|
---
|
|
|
|
## Cross-Reference: Three Repositories Compared
|
|
|
|
| Capability | Claude Code Source | open-multi-agent | claw-code |
|
|
|---|---|---|---|
|
|
| Agent orchestration | Production, feature-gated | Clean abstraction, pre-release | Partial reimplementation |
|
|
| Multi-agent coordination | Swarms/Teammates + SendMessage | MessageBus + SharedMemory | Not implemented |
|
|
| Memory system | File-based + LLM relevance filter | SharedMemory (in-process only) | Not implemented |
|
|
| Tool harness | Full buildTool() + Zod schemas | Zod-validated custom tools | Partial port |
|
|
| MCP integration | Full client + OAuth + approvals | None | None |
|
|
| Task scheduling | Four task types + background | Topological + 4 strategies | None |
|
|
| Skills framework | Directory-based + bundled | None | None |
|
|
| Maturity | Production (millions of users) | v0.1.0 | Alpha |
|
|
---
|
|
|
|
## Strategic Recommendations for Waggle
|
|
|
|
### Immediate (adopt patterns, not code):
|
|
|
|
1. **Agent definition schema** — standardize on the `agentType + tools + disallowedTools + whenToUse + model` pattern.
|
|
2. **Memory taxonomy** — implement the four-type system (user/feedback/project/reference) as a schema layer on your graph DB.
|
|
3. **Side-query relevance** — use a lightweight model call to pre-filter which memories/context to inject per query.
|
|
4. **Deferred tool loading** — implement ToolSearch-like pattern as connector count grows.
|
|
|
|
### Near-term (architecture alignment):
|
|
|
|
5. **Coordinator mode** — implement a Mission Control agent that only delegates, never executes.
|
|
6. **Fork subagent** — enable context-inheriting spawns for research workflows in Waggle Dance.
|
|
7. **Token budget management** — build a budget allocator for system prompt, history, and tool results.
|
|
8. **Background agents with notifications** — critical UX for desktop app.
|
|
|
|
### Strategic (differentiation layer):
|
|
|
|
9. **Waggle's graph memory > Claude Code's flat files** — this is your advantage. The graph enables relationship queries, temporal reasoning, and cross-agent knowledge sharing that flat files cannot. Lean into this.
|
|
10. **Visual orchestration > CLI text** — Waggle's Cockpit/Mission Control/Waggle Dance provide visibility that Claude Code's terminal cannot match. This is the enterprise moat.
|
|
11. **Multi-workspace isolation** — Claude Code has one project context per session. Waggle's workspace isolation is architecturally superior for enterprise.
|
|
|
|
### What NOT to do:
|
|
|
|
- Do NOT copy code. IP risk is real regardless of "clean room" claims.
|
|
- Do NOT adopt the tmux-based multi-agent pattern. It's a CLI-specific hack. Waggle's backend can orchestrate agents natively.
|
|
- Do NOT replicate the terminal rendering layer (ink/). Waggle is a desktop app with a proper UI framework.
|
|
- Do NOT adopt the file-based memory storage. Keep the graph DB — just adopt the taxonomy and retrieval patterns.
|
|
---
|
|
|
|
## Verdict on open-multi-agent (Updated)
|
|
|
|
After seeing Claude Code's architecture, open-multi-agent's value proposition shifts. Claude Code already demonstrates production-grade agent orchestration, but it's tightly coupled to the CLI and Anthropic's infrastructure. open-multi-agent offers a **cleaner abstraction** for the orchestration layer specifically — its TaskQueue with topological scheduling, MessageBus, and capability-matching scheduler are architecturally elegant and model-agnostic.
|
|
|
|
**Revised recommendation:** open-multi-agent remains worth evaluating as an orchestration layer, particularly because it's MIT-licensed and model-agnostic. Use Claude Code as the design reference, open-multi-agent as a potential dependency.
|
|
|
|
## Verdict on claw-code (Unchanged)
|
|
|
|
Pass. Claude Code source itself is available for reference. A partial reimplementation adds no value and carries IP risk.
|
|
---
|
|
|
|
## CORRECTION: Memory System Assessment (Updated)
|
|
|
|
The original analysis incorrectly characterized Waggle's graph database memory as "potentially over-engineered." This has been corrected after examining the actual implementation.
|
|
|
|
**Waggle's memory architecture (SQLite + frames + graph) is structurally superior to Claude Code's flat-file approach.** Frames as graph nodes with relational edges enable relationship queries, temporal reasoning, cross-agent knowledge sharing, and importance-based pruning — none of which flat markdown files can deliver. The `auto_recall` tool provides automatic context injection that Claude Code achieves only through a more primitive file-scan + LLM-filter pipeline.
|
|
|
|
**What to adopt from Claude Code (as a layer on the graph, not a replacement):**
|
|
|
|
1. **Side-query relevance filter** — scan frame metadata, select top-5 per query, inject only those. This is the single highest-value pattern to port.
|
|
2. **Staleness warnings** — inject freshness caveats for frames older than a configurable threshold.
|
|
3. **"Verify before recommending" enforcement** — when a frame references a specific file, function, or resource, verify it still exists before surfacing it.
|
|
4. **Four-type taxonomy** — map frame types to user/feedback/project/reference for consistent classification.
|
|
|
|
**Implementation bugs to fix (not architecture issues):**
|
|
- `accessCount` never increments (breaks importance scoring)
|
|
- Memory count discrepancy (49 vs 37 in different UI views)
|
|
- Markdown not rendered in frame display |