# taewooopark/motifcode architecture

> Architecture diagram of the GitHub repository taewooopark/motifcode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taewooopark/motifcode
- Repository: https://github.com/taewooopark/motifcode

## Overview

Motifcode is a Motif-3-specific terminal coding-agent harness. The principal workflow starts at the CLI, opens an interactive chat, runs the model/tool loop, and presents results in the terminal UI. Separate branches cover configuration and login, MCP integrations, session persistence, subagents and skills, and evaluation. Edges reflect README statements or source-index references and excerpts; unsampled implementation details are not inferred.

Main entry points: [`packages/cli/src/chat.ts`](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/chat.ts) (Interactive chat), [`packages/cli/src/main.ts`](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/main.ts) (CLI entry), [`packages/mcp/src/manager.ts`](https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/manager.ts) (MCP manager), [`packages/core/src/loop.ts`](https://github.com/taewooopark/motifcode/blob/main/packages/core/src/loop.ts) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and session"]
  node_cli["CLI entry<br/>[main.ts]"]
  node_chat["Interactive chat<br/>[chat.ts]"]
  node_commands["Slash commands<br/>[commands.ts]"]
  node_login["Login and keys<br/>[login.ts]"]
  node_settings["Settings<br/>[settings.ts]"]
  node_files["Project files<br/>[files.ts]"]
  node_journal[("Session journal<br/>[index.ts]")]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Agent loop<br/>[loop.ts]"]
  node_session["Context ledger<br/>[session.ts]"]
  node_executor["Tool execution<br/>[executor.ts]"]
  node_policy["Permission policy<br/>[policy.ts]"]
  node_protocol["Model protocol<br/>[toolcall.ts]"]
end

subgraph group_integrations["Tools and integrations"]
  node_skills["Skills<br/>[builtin.ts]"]
  node_agents["Subagents<br/>[index.ts]"]
  node_mcpconfig["MCP configuration<br/>[config.ts]"]
  node_mcpmanager["MCP manager<br/>[manager.ts]"]
  node_mcpclient["MCP connection<br/>[client.ts]"]
  node_mcpauth["MCP OAuth<br/>[auth.ts]"]
end

subgraph group_experience["Terminal experience"]
  node_tui["Terminal interface<br/>[screen.ts]"]
  node_doctor["Diagnostics<br/>[doctor.ts]"]
  node_insights["Usage insights<br/>[insights.ts]"]
end

subgraph group_modeling["Model fit and evaluation"]
  node_eval["Agent evaluation<br/>[suite-cli.ts]"]
end

node_user(("Developer"))

node_user -->|"starts"| node_cli
node_cli -->|"opens session"| node_chat
node_cli -->|"handles sign-in"| node_login
node_cli -->|"loads config"| node_mcpconfig
node_chat -->|"runs"| node_loop
node_chat -->|"parses commands"| node_commands
node_chat -->|"updates interface"| node_tui
node_chat -.->|"persists session"| node_journal
node_chat -->|"uses skills"| node_skills
node_chat -->|"uses MCP context"| node_mcpmanager
node_loop -->|"manages context"| node_session
node_loop -.->|"uses tool parsing"| node_protocol
node_chat -.->|"dispatches tools"| node_executor
node_executor -->|"applies policy"| node_policy
node_executor -->|"uses skills"| node_skills
node_chat -.->|"supports delegation"| node_agents
node_mcpmanager -->|"resolves servers"| node_mcpconfig
node_mcpmanager -->|"opens connection"| node_mcpclient
node_mcpmanager -->|"uses broker"| node_mcpauth
node_mcpclient -->|"authorizes access"| node_mcpauth
node_cli -->|"runs diagnostics"| node_doctor
node_cli -->|"handles settings"| node_settings
node_chat -->|"uses project files"| node_files
node_cli -.->|"offers insights"| node_insights
node_eval -->|"evaluates runs"| node_loop

click node_cli "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/main.ts"
click node_chat "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/chat.ts"
click node_commands "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/commands.ts"
click node_login "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/login.ts"
click node_settings "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/settings.ts"
click node_files "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/files.ts"
click node_journal "https://github.com/taewooopark/motifcode/blob/main/packages/journal/src/index.ts"
click node_loop "https://github.com/taewooopark/motifcode/blob/main/packages/core/src/loop.ts"
click node_session "https://github.com/taewooopark/motifcode/blob/main/packages/core/src/session.ts"
click node_executor "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/executor.ts"
click node_policy "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/policy.ts"
click node_protocol "https://github.com/taewooopark/motifcode/blob/main/packages/protocol/src/toolcall.ts"
click node_skills "https://github.com/taewooopark/motifcode/blob/main/packages/skills/src/builtin.ts"
click node_agents "https://github.com/taewooopark/motifcode/blob/main/packages/agents/src/index.ts"
click node_mcpconfig "https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/config.ts"
click node_mcpmanager "https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/manager.ts"
click node_mcpclient "https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/client.ts"
click node_mcpauth "https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/auth.ts"
click node_tui "https://github.com/taewooopark/motifcode/blob/main/packages/tui/src/screen.ts"
click node_doctor "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/doctor.ts"
click node_insights "https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/insights.ts"
click node_eval "https://github.com/taewooopark/motifcode/blob/main/packages/eval/src/suite-cli.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_chat,node_commands,node_login,node_settings,node_files,node_journal toneBlue
class node_loop,node_session,node_executor,node_policy,node_protocol toneAmber
class node_skills,node_agents,node_mcpconfig,node_mcpmanager,node_mcpclient,node_mcpauth toneMint
class node_tui,node_doctor,node_insights toneRose
class node_eval,node_user toneIndigo
```

## Components

### CLI and session

- [CLI entry](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/main.ts): `packages/cli/src/main.ts`
- [Interactive chat](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/chat.ts): `packages/cli/src/chat.ts`
- [Slash commands](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/commands.ts): `packages/cli/src/commands.ts`
- [Login and keys](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/login.ts): `packages/cli/src/login.ts`
- [Settings](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/settings.ts): `packages/cli/src/settings.ts`
- [Project files](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/files.ts): `packages/cli/src/files.ts`
- [Session journal](https://github.com/taewooopark/motifcode/blob/main/packages/journal/src/index.ts): `packages/journal/src/index.ts`

### Agent runtime

- [Agent loop](https://github.com/taewooopark/motifcode/blob/main/packages/core/src/loop.ts): `packages/core/src/loop.ts`
- [Context ledger](https://github.com/taewooopark/motifcode/blob/main/packages/core/src/session.ts): `packages/core/src/session.ts`
- [Tool execution](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/executor.ts): `packages/cli/src/executor.ts`
- [Permission policy](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/policy.ts): `packages/cli/src/policy.ts`
- [Model protocol](https://github.com/taewooopark/motifcode/blob/main/packages/protocol/src/toolcall.ts): `packages/protocol/src/toolcall.ts`

### Tools and integrations

- [Skills](https://github.com/taewooopark/motifcode/blob/main/packages/skills/src/builtin.ts): `packages/skills/src/builtin.ts`
- [Subagents](https://github.com/taewooopark/motifcode/blob/main/packages/agents/src/index.ts): `packages/agents/src/index.ts`
- [MCP configuration](https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/config.ts): `packages/mcp/src/config.ts`
- [MCP manager](https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/manager.ts): `packages/mcp/src/manager.ts`
- [MCP connection](https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/client.ts): `packages/mcp/src/client.ts`
- [MCP OAuth](https://github.com/taewooopark/motifcode/blob/main/packages/mcp/src/auth.ts): `packages/mcp/src/auth.ts`

### Terminal experience

- [Terminal interface](https://github.com/taewooopark/motifcode/blob/main/packages/tui/src/screen.ts): `packages/tui/src/screen.ts`
- [Diagnostics](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/doctor.ts): `packages/cli/src/doctor.ts`
- [Usage insights](https://github.com/taewooopark/motifcode/blob/main/packages/cli/src/insights.ts): `packages/cli/src/insights.ts`

### Model fit and evaluation

- [Agent evaluation](https://github.com/taewooopark/motifcode/blob/main/packages/eval/src/suite-cli.ts): `packages/eval/src/suite-cli.ts`

### Other components

- **Developer**

## Connections

- Developer → CLI entry: starts (evidence: `README.md`)
- CLI entry → Interactive chat: opens session (evidence: `packages/cli/src/main.ts`)
- CLI entry → Login and keys: handles sign-in (evidence: `packages/cli/src/main.ts`)
- CLI entry → MCP configuration: loads config (evidence: `packages/cli/src/main.ts`)
- Interactive chat → Agent loop: runs (evidence: `packages/cli/src/chat.ts`)
- Interactive chat → Slash commands: parses commands (evidence: `packages/cli/src/chat.ts`)
- Interactive chat → Terminal interface: updates interface (evidence: `packages/cli/src/chat.ts`)
- Interactive chat → Session journal: persists session
- Interactive chat → Skills: uses skills (evidence: `packages/cli/src/chat.ts`)
- Interactive chat → MCP manager: uses MCP context (evidence: `packages/cli/src/chat.ts`)
- Agent loop → Context ledger: manages context (evidence: `packages/core/src/loop.ts`)
- Agent loop → Model protocol: uses tool parsing
- Interactive chat → Tool execution: dispatches tools (evidence: `packages/cli/src/chat.ts`)
- Tool execution → Permission policy: applies policy (evidence: `packages/cli/src/executor.ts`)
- Tool execution → Skills: uses skills (evidence: `packages/cli/src/executor.ts`)
- Interactive chat → Subagents: supports delegation
- MCP manager → MCP configuration: resolves servers (evidence: `packages/mcp/src/manager.ts`)
- MCP manager → MCP connection: opens connection (evidence: `packages/mcp/src/manager.ts`)
- MCP manager → MCP OAuth: uses broker (evidence: `packages/mcp/src/manager.ts`)
- MCP connection → MCP OAuth: authorizes access (evidence: `packages/mcp/src/client.ts`)
- CLI entry → Diagnostics: runs diagnostics (evidence: `packages/cli/src/main.ts`)
- CLI entry → Settings: handles settings (evidence: `packages/cli/src/main.ts`)
- Interactive chat → Project files: uses project files (evidence: `packages/cli/src/chat.ts`)
- CLI entry → Usage insights: offers insights
- Agent evaluation → Agent loop: evaluates runs (evidence: `packages/eval/src/suite-cli.ts`)
