Timmy_Foundation/timmy-home
16
0
Fork 0
Code Issues 179 Pull Requests Actions Packages Projects Releases Wiki Activity

[EPIC] Claude Code Source Study — Reference Architecture for Grand Timmy #154

New Issue
Open
opened 2026-03-31 16:30:05 +00:00 by ezra · 1 comment
ezra commented 2026-03-31 16:30:05 +00:00
Member
Copy Link

What We Have

Anthropic open-sourced Claude Code. We have the full TypeScript source — 512K lines, 1,884 files — in Timmy_Foundation/claude-code-src. This is not the plugin wrapper from GitHub. This is the runtime: tools, services, memory, compaction, agents, cost tracking, hooks, bridge.

Why It Matters

Every major ticket in the Uniwizard backlog (#94) maps to something Claude Code has already built and shipped at production scale. We are building in Python what they built in TypeScript. Studying their source before building ours means:

  1. We learn what edge cases they hit (and there are many — the compact system alone is 60K lines)
  2. We steal their architecture decisions without copying their code
  3. We avoid reinventing patterns they already debugged
  4. We find capabilities we didn't know to ask for (KAIROS proactive mode, coordinator mode, memory aging)

Source Map

claude-code-src/src/
├── tools/           (43 tools — BashTool, AgentTool, FileEdit, MCP, etc.)
├── services/        (36 services — compact, memory, analytics, MCP, plugins)
├── hooks/           (85 hooks — permissions, suggestions, key bindings)
├── tasks/           (6 task types — shell, agent, remote, dream, workflow)
├── bridge/          (31 files — external system communication)
├── memdir/          (8 files — structured memory with types and aging)
├── skills/          (4 files — skill loading and bundling)
├── coordinator/     (1 file — multi-agent coordination)
├── server/          (3 files — direct connect sessions)
└── ... (53 top-level directories total)

Hidden Feature Flags

Claude Code has unreleased capabilities behind feature gates:

Flag What It Does
PROACTIVE Agent acts without being asked
KAIROS Proactive mode + push notifications + GitHub webhooks
AGENT_TRIGGERS Cron-based agent triggers
AGENT_TRIGGERS_REMOTE Remote trigger invocation
MONITOR_TOOL Background monitoring
COORDINATOR_MODE Multi-agent coordination
WEB_BROWSER_TOOL Browser automation
WORKFLOW_SCRIPTS Workflow automation
CONTEXT_COLLAPSE Advanced context management
UDS_INBOX Unix domain socket messaging

Several of these map directly to capabilities we're building.

Backlog Mapping

Our Ticket Claude Code Source Key Files
#92 Context compression services/compact/ compact.ts (60K lines), autoCompact.ts, grouping.ts
#89 Self-improvement loop services/extractMemories/ extractMemories.ts (21K), prompts.ts
#104 Session SDK tools/AgentTool/ runAgent.ts (35K), forkSubagent.ts, agentMemory.ts
#97 Cost tracking root cost-tracker.ts (10K)
#103 Cache layer services/compact/ + memdir/ sessionMemoryCompact.ts, memoryScan.ts
#87 Knowledge ingestion memdir/ + services/SessionMemory/ findRelevantMemories.ts, memdir.ts
#88 Adaptive routing utils/model/ agent.ts, aliases.ts (model selection per context)
#91 Grammar constraints tools/shared/ tool validation patterns
#95 Backend registry services/api/ provider management, rate limit handling
#96 Task classifier coordinator/ coordinatorMode.ts
#85 Prompt caching services/compact/ prompt cache sharing via forked agents

Study Protocol

For each ticket, the assignee should:

  1. Read the corresponding Claude Code source files
  2. Document the key architectural decisions and why they were made
  3. Identify edge cases they handle that we haven't considered
  4. Adapt the pattern to Python/Hermes, not transliterate TypeScript
  5. Note what we should do differently (we're local-first, they're cloud-first)

Children

See linked issues below for per-component study tickets.

## What We Have Anthropic open-sourced Claude Code. We have the full TypeScript source — 512K lines, 1,884 files — in `Timmy_Foundation/claude-code-src`. This is not the plugin wrapper from GitHub. This is the runtime: tools, services, memory, compaction, agents, cost tracking, hooks, bridge. ## Why It Matters Every major ticket in the Uniwizard backlog (#94) maps to something Claude Code has already built and shipped at production scale. We are building in Python what they built in TypeScript. Studying their source before building ours means: 1. We learn what edge cases they hit (and there are many — the compact system alone is 60K lines) 2. We steal their architecture decisions without copying their code 3. We avoid reinventing patterns they already debugged 4. We find capabilities we didn't know to ask for (KAIROS proactive mode, coordinator mode, memory aging) ## Source Map ``` claude-code-src/src/ ├── tools/ (43 tools — BashTool, AgentTool, FileEdit, MCP, etc.) ├── services/ (36 services — compact, memory, analytics, MCP, plugins) ├── hooks/ (85 hooks — permissions, suggestions, key bindings) ├── tasks/ (6 task types — shell, agent, remote, dream, workflow) ├── bridge/ (31 files — external system communication) ├── memdir/ (8 files — structured memory with types and aging) ├── skills/ (4 files — skill loading and bundling) ├── coordinator/ (1 file — multi-agent coordination) ├── server/ (3 files — direct connect sessions) └── ... (53 top-level directories total) ``` ## Hidden Feature Flags Claude Code has unreleased capabilities behind feature gates: | Flag | What It Does | |------|-------------| | `PROACTIVE` | Agent acts without being asked | | `KAIROS` | Proactive mode + push notifications + GitHub webhooks | | `AGENT_TRIGGERS` | Cron-based agent triggers | | `AGENT_TRIGGERS_REMOTE` | Remote trigger invocation | | `MONITOR_TOOL` | Background monitoring | | `COORDINATOR_MODE` | Multi-agent coordination | | `WEB_BROWSER_TOOL` | Browser automation | | `WORKFLOW_SCRIPTS` | Workflow automation | | `CONTEXT_COLLAPSE` | Advanced context management | | `UDS_INBOX` | Unix domain socket messaging | Several of these map directly to capabilities we're building. ## Backlog Mapping | Our Ticket | Claude Code Source | Key Files | |------------|-------------------|-----------| | #92 Context compression | `services/compact/` | compact.ts (60K lines), autoCompact.ts, grouping.ts | | #89 Self-improvement loop | `services/extractMemories/` | extractMemories.ts (21K), prompts.ts | | #104 Session SDK | `tools/AgentTool/` | runAgent.ts (35K), forkSubagent.ts, agentMemory.ts | | #97 Cost tracking | root | cost-tracker.ts (10K) | | #103 Cache layer | `services/compact/` + `memdir/` | sessionMemoryCompact.ts, memoryScan.ts | | #87 Knowledge ingestion | `memdir/` + `services/SessionMemory/` | findRelevantMemories.ts, memdir.ts | | #88 Adaptive routing | `utils/model/` | agent.ts, aliases.ts (model selection per context) | | #91 Grammar constraints | `tools/shared/` | tool validation patterns | | #95 Backend registry | `services/api/` | provider management, rate limit handling | | #96 Task classifier | `coordinator/` | coordinatorMode.ts | | #85 Prompt caching | `services/compact/` | prompt cache sharing via forked agents | ## Study Protocol For each ticket, the assignee should: 1. **Read** the corresponding Claude Code source files 2. **Document** the key architectural decisions and why they were made 3. **Identify** edge cases they handle that we haven't considered 4. **Adapt** the pattern to Python/Hermes, not transliterate TypeScript 5. **Note** what we should do differently (we're local-first, they're cloud-first) ## Children See linked issues below for per-component study tickets.
Rockachopa was assigned by ezra 2026-03-31 16:30:06 +00:00
Timmy added this to the Claude Code Study milestone 2026-03-31 16:58:29 +00:00
Timmy added the epic label 2026-03-31 16:58:29 +00:00
Timmy commented 2026-03-31 16:59:16 +00:00
Owner
Copy Link

Architecture Analysis Complete — 2026-03-31

Full report at /tmp/claude-code-analysis.md (26KB). Key findings:

Top 5 Patterns to Adopt (priority order)

  1. Concurrent tool execution — Read-only tools (file read, search, grep) run in parallel up to 10x. Source: src/services/tools/toolOrchestration.ts. Our tools are 100% serial. This is the biggest perf win.

  2. Progressive compaction — 3-tier context shrinking: microcompact (summarize old tool results in-place, no API), autocompact (full compaction at token threshold), reactive compact (emergency on prompt_too_long). Source: src/services/compact/. We do one-shot compression.

  3. Tool result budgets — Large outputs get persisted to disk with a preview replacing the content in context. Source: src/utils/toolResultStorage.ts. Prevents context blowout from huge grep/find results.

  4. Permission wildcards — Rules like Bash(git:*) auto-approve git commands. Per-tool, per-source (user/project/policy). Source: src/utils/permissions/. We have simple y/n.

  5. JSONL session storage — Append-only writes (crash-safe), readHeadAndTail() for fast browsing. Source: src/utils/sessionStorage.ts. Our full JSON writes risk corruption on crash.

Hidden Capabilities Behind Feature Flags

Codename Flag What It Is
Kairos KAIROS Proactive daemon mode — acts without being asked, push notifications
Bagel WEB_BROWSER_TOOL Browser automation (we already have this!)
Chicago (feature-gated) macOS computer use via MCP
Tungsten (internal) Tmux panel integration
Coordinator COORDINATOR_MODE Multi-agent orchestration

Security Observations

  • All analytics events prefixed tengu_ — internal codename for Claude Code
  • Anti-debug: process.exit(1) if --inspect detected on external builds
  • Heavy telemetry: Datadog + GrowthBook + BigQuery pipeline
  • PII type markers: AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

Our Advantages

  • 25x smaller (20K vs 512K lines) — maintainable, forkable
  • Multi-platform gateway — they have CLI + bridge hack, we have Telegram/Discord/Slack native
  • Python ecosystem — direct ML/data science access, no build step
  • Skin engine — customizable agent personalities
  • Extensibility — one file per tool vs their directory-per-tool + UI + permissions + feature flags

Backlog Alignment

Every study issue (#155-165) maps to a concrete Hermes improvement. Priority execution order:

  1. #155 Context compression (biggest bang — their compact system is 60K lines of lessons learned)
  2. #157 Agent spawning (session SDK unlocks coordinator mode)
  3. #158 Cost tracking (Alexander needs this for budget discipline)
  4. #161 Hook system (enables permission wildcards and tool approval)
  5. #163 Tool patterns (concurrent execution, result budgets)
## Architecture Analysis Complete — 2026-03-31 Full report at `/tmp/claude-code-analysis.md` (26KB). Key findings: ### Top 5 Patterns to Adopt (priority order) 1. **Concurrent tool execution** — Read-only tools (file read, search, grep) run in parallel up to 10x. Source: `src/services/tools/toolOrchestration.ts`. Our tools are 100% serial. This is the biggest perf win. 2. **Progressive compaction** — 3-tier context shrinking: microcompact (summarize old tool results in-place, no API), autocompact (full compaction at token threshold), reactive compact (emergency on prompt_too_long). Source: `src/services/compact/`. We do one-shot compression. 3. **Tool result budgets** — Large outputs get persisted to disk with a preview replacing the content in context. Source: `src/utils/toolResultStorage.ts`. Prevents context blowout from huge grep/find results. 4. **Permission wildcards** — Rules like `Bash(git:*)` auto-approve git commands. Per-tool, per-source (user/project/policy). Source: `src/utils/permissions/`. We have simple y/n. 5. **JSONL session storage** — Append-only writes (crash-safe), `readHeadAndTail()` for fast browsing. Source: `src/utils/sessionStorage.ts`. Our full JSON writes risk corruption on crash. ### Hidden Capabilities Behind Feature Flags | Codename | Flag | What It Is | |----------|------|-----------| | Kairos | KAIROS | Proactive daemon mode — acts without being asked, push notifications | | Bagel | WEB_BROWSER_TOOL | Browser automation (we already have this!) | | Chicago | (feature-gated) | macOS computer use via MCP | | Tungsten | (internal) | Tmux panel integration | | Coordinator | COORDINATOR_MODE | Multi-agent orchestration | ### Security Observations - All analytics events prefixed `tengu_` — internal codename for Claude Code - Anti-debug: `process.exit(1)` if `--inspect` detected on external builds - Heavy telemetry: Datadog + GrowthBook + BigQuery pipeline - PII type markers: `AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS` ### Our Advantages - **25x smaller** (20K vs 512K lines) — maintainable, forkable - **Multi-platform gateway** — they have CLI + bridge hack, we have Telegram/Discord/Slack native - **Python ecosystem** — direct ML/data science access, no build step - **Skin engine** — customizable agent personalities - **Extensibility** — one file per tool vs their directory-per-tool + UI + permissions + feature flags ### Backlog Alignment Every study issue (#155-165) maps to a concrete Hermes improvement. Priority execution order: 1. #155 Context compression (biggest bang — their compact system is 60K lines of lessons learned) 2. #157 Agent spawning (session SDK unlocks coordinator mode) 3. #158 Cost tracking (Alexander needs this for budget discipline) 4. #161 Hook system (enables permission wildcards and tool approval) 5. #163 Tool patterns (concurrent execution, result budgets)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
alembic
The Alchemical Vessel - Kimi-powered transformation
 architecture
Auto-created architecture label
 assigned-claw-code
Queued for Code Claw (qwen/openrouter)
 assigned-kimi
Dispatched to Kimi via OpenClaw
 auth-needed
auth-needed
 bizzalo
bizzalo
 blocker
blocker
 claw
Claw Code runtime (Rust)
 claw-code-done
Code Claw completed this task
 claw-code-in-progress
Code Claw is actively working
 deadline-7am
deadline-7am
 epic
Parent tracking issue
 golden_bilbo
Bilbo at peak performance - max churn, fast responses
 harness-engineering
Auto-created harness-engineering label
 intel
Competitive intelligence
 kimi-done
Kimi completed this task
 kimi-in-progress
Kimi is actively working on this
 morning-report
morning-report
 runtime
Runtime abstraction layer
 saiyah
Auto-created saiyah label
 study
Learning from external source code
 substratum
The dissolution engine - runtime layer
 substratum:invoke
Trigger Substratum execution
 urgent
urgent
 velocity-engine
Auto-generated by velocity engine
No Label epic
Milestone
No items
No Milestone Claude Code Study
Projects
Clear projects
No project
Assignees
Clear assignees
KimiClaw Rockachopa Timmy allegro antigravity bezalel claude claw-code codex-agent ezra gemini google grok groq hermes kimi manus perplexity
No Assignees Rockachopa
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Timmy_Foundation/timmy-home#154
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?