Architecture

System diagrams and data flows for the Claude Agent OS. All diagrams reflect the production implementation.

System Component Map

How the major subsystems relate at runtime. Four environment groupings: Runtime, Triggers, Skill Execution, External Integrations, and Persistence.

Context Injection Architecture

How state reaches Claude's context window at session start. No RAG. No embeddings. Two-layer guaranteed injection: CLAUDE.md (always loaded) + hooks (deterministic lifecycle commands).

Lifecycle Automation Hooks

Shell commands wired to Claude Code lifecycle events in .claude/settings.json. Hooks run outside the model's context window — deterministic OS-level automation, not AI instructions.

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "python3 .claude/hooks/session-start.py", "timeout": 10 }] }
    ],
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "python3 .claude/hooks/pre-compact.py", "timeout": 15 }] }
    ],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "bash .claude/hooks/session-end-snapshot.sh", "timeout": 60 }] }
    ],
    "PostToolUse": [
      { "matcher": "Skill", "hooks": [{ "type": "command", "command": "python3 .claude/hooks/log-skill-run.py", "timeout": 10 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "python3 .claude/hooks/log-slash-skill.py", "timeout": 10 }] }
    ]
  }
}

Full Production Session

End-to-end data flow for a content creation session using the /youtube-pipeline skill.

Weekly OS Audit (Scheduled)

Fires every Friday at 4am CT via RemoteTrigger. No human input required.

Components

Detailed specification for each of the seven core components of the Agent OS. Each component is independent and composable.

# CLAUDE.md

## Context Files
- @context/me.md
- @context/work.md
- @context/current-priorities.md

## Active Projects
| Project | Description |
|---------|-------------|
| `projects/[name]/` | [Status and description] |

**Hygiene rule:** Projects enter the table when they have a folder + active work.
Projects exit only when moved to archives/ AND logged in decisions/log.md.

✅  Completed — done, ship it, move on
- [ ]  Pending — active, in queue
⏸  Parked — deliberately deferred, not forgotten

# execution-mode.md

[Operator's documented failure mode — e.g., "Default pattern:
research > refine > optimize > never ship."]

## Rules of Engagement

1. **Bias toward shipping.** "Good enough" beats "perfect but
   unpublished" every time.
2. **One review pass.** When reviewing content — do ONE thorough
   pass. Don't suggest a second round unless something is
   genuinely broken.
3. **Don't feed the research spiral.** If the operator asks to
   "look into" something tangential to top priorities, flag it
   and suggest parking it.
...

---
name: skill-name              # Machine-readable identifier
description: >                # Used by Claude to determine when to invoke
  [Detailed trigger conditions and purpose]
trigger: /skill-name          # The /command that activates this skill
status: active                # active | deprecated | experimental
---

# Skill Title

## What It Does
[Plain English summary]

## Mode Selection (optional)
[Parse user input to determine execution path]

## Steps
### Phase 1 — [Name]
[Specific instructions — what to read, generate, where to write]

**Gate:** Present output to user. Wait for approval before proceeding.

### Phase 2 — [Name]
...

## Output
[Where output lands and in what format]

Active skill:      .claude/skills/[name]/SKILL.md   # status: active
Deprecated skill:  archives/[YYYY-MM-DD]-skill-[name]-deprecated/

---
name: [memory name]
description: [one-line hook — used to determine relevance at load time]
type: user | feedback | project | reference
---

[Memory content]

**Why:** [The reason this matters]
**How to apply:** [When this kicks in]

# Memory Index

## Feedback
- [Anti-pattern: never batch publish](feedback_no_batch_publish.md) — violated 2026-04-08, burned
- [Platform: YouTube API scope requirements](feedback_youtube_api.md) — force-ssl required for comments

## Projects
- [Project: Run AI product](project_run_ai.md) — $147, live on Systeme.io 2026-05-04

[YYYY-MM-DD] DECISION: [What was decided]
            | REASONING: [Why]
            | CONTEXT: [Where it affects the system]

API Reference

Complete schema definitions, format specifications, and configuration reference for all Agent OS components.

Skill File Schema

YAML frontmatter required fields. File location: .claude/skills/[name]/SKILL.md

Memory File Schema

YAML frontmatter required fields. Files live in ~/.claude/projects/[path]/memory/

MCP Server Configuration

File: .mcp.json in workspace root. Loaded by Claude Code on session start.

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-google-calendar"],
      "env": { "GOOGLE_OAUTH_TOKEN": "..." }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": { "NOTION_TOKEN": "..." }
    }
  }
}

MCP Selection Hierarchy

Follow in order. Never fall through silently from a higher tier to a lower tier when a tool errors.

Decision Log Format

[YYYY-MM-DD] DECISION: [What was decided]
            | REASONING: [Why — include the alternatives considered]
            | CONTEXT: [Which files or components this affects]

# Examples:
[2026-05-01] DECISION: Use file-based context over vector RAG
            | REASONING: Deterministic retrieval, no infrastructure,
              debuggable — for bounded single-operator context, full
              injection is more reliable than retrieval
            | CONTEXT: context/*.md, CLAUDE.md, Memory architecture

Credential Storage Pattern

~/.config/fiti-youtube/
├── client_secrets.json   # OAuth app credentials — NOT in repo
└── token.json            # Cached access + refresh token (auto-refreshes)

# Git credential helper (never embed tokens in remote URLs)
git config --local credential.helper osxkeychain
git remote set-url origin https://github.com/[user]/[repo].git

.gitignore Minimums

*.env
client_secrets.json
token.json
.mcp.json          # if it contains inline credentials

Guides

Runbooks and how-to guides for common operations. Each guide is a self-contained procedure.

Session Startup Sequence

Adding a New Skill

Adding a New MCP Server

Project Lifecycle

Adding a Project

Retiring a Project

Recovering from Stale Context

Scaling to a Team

The single-operator model scales to small teams with these modifications:

Replacing File Storage with a Knowledge Base

For teams needing search across a larger document corpus:

FAQ & Trade-offs

Design decisions, anti-patterns, security considerations, and observability model for the Agent OS.

Design Decisions

Anti-Patterns

Security Considerations

Observability

No metrics dashboard by default. Observability is achieved through structured file outputs and the weekly audit.

Common Questions