# codeany-ai/codeany architecture

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

- Interactive diagram: https://gitdiagram.com/codeany-ai/codeany
- Repository: https://github.com/codeany-ai/codeany

## Overview

1. **What this repo is**
   - `codeany` is a single Go CLI application that runs as an interactive terminal agent.
   - The core UX is a Bubble Tea TUI, with a non-interactive “pipe/print” mode for scripting and shell usage.
   - The app integrates with the Open Agent SDK and external model providers via API keys and base URLs.

2. **Process entrypoint and CLI boundary**
   - `cmd/codeany/main.go` is the executable entrypoint.
   - `internal/cli/root.go` appears to own top-level command-line parsing and mode selection.
   - From there, execution branches into interactive TUI, piped input, print mode, update flows, and possibly help/version paths.

3. **Interaction model: TUI vs. pipe mode**
   - `internal/tui/*` contains the primary interactive shell: input handling, rendering, and the Bubble Tea model.
   - `internal/pipe/pipe.go` handles stdin-driven workflows such as `echo "question" | codeany -p`.
   - This is an important architectural boundary: the same agent backend is reused, but the front-end interaction layer differs.

4. **Conversation/session state**
   - `internal/session/session.go` manages conversation lifecycle and persistence of session history.
   - The README’s `~/.codeany/sessions/` directory suggests sessions are stored locally for resume/export/status features.
   - This layer is likely where turn history, current context, and session metadata are normalized before being shown in the TUI or sent to the model.

5. **Context sources and local project awareness**
   - `internal/memory/memory.go` suggests long-lived local memory or recalled facts stored under `~/.codeany/memory/`.
   - `internal/worktree/worktree.go` likely provides repository/worktree inspection and file-system awareness for code tasks.
   - Together with `CODEANY.md`, `.codeany/rules`, and session state, these form the local context assembly pipeline that feeds the agent.

6. **Configuration and permission boundary**
   - `internal/config/config.go` and `internal/config/permissions.go` centralize application settings and authorization rules.
   - The README shows config stored in `~/.codeany/settings.json`, `permissions.json`, and optional YAML.
   - This layer controls model selection, max turns, MCP server definitions, hooks, and permission mode, which directly affects what the agent can do without prompting.

7. **Tooling and extensibility**
   - `internal/plugins/plugins.go` and `internal/skills/skills.go` implement the extension system described in the README.
   - Skills live in local markdown files and expose reusable task instructions; plugins appear to package reusable capability bundles.
   - `internal/slash/commands.go` and `internal/slash/slash.go` wire the 41+ slash commands into the interactive runtime.
   - This is the main command-routing boundary for user-driven operations like `/plan`, `/review`, `/test`, `/mcp`, `/config`, and `/resume`.

8. **Agent orchestration and domain capabilities**
   - `internal/team/team.go` and possibly other orchestration packages represent higher-level workflows beyond raw chat.
   - The README commands like `/commit`, `/bug`, `/review`, and `/test` imply specialized agent behaviors layered on top of the base chat loop.
   - The architecture therefore separates “chat transport” from “task orchestration,” which helps preserve reusable workflows.

9. **UI presentation and feedback**
   - `internal/theme/*` provides visual affordances such as spinners and styling.
   - `internal/tui/render.go` is responsible for presenting conversation state, tool output, and command results.
   - This layer is purely presentation-facing: it reflects state from session/agent logic but should not own core business rules.

10. **Runtime integrations and external services**
   - Model access is API-driven, using `ANTHROPIC_API_KEY` or `CODEANY_API_KEY` plus optional `CODEANY_BASE_URL`.
   - MCP server support is first-class and configured through local settings, so the app can delegate tools to external processes.
   - Git and filesystem access are important environment dependencies, especially for features like diff, commit helper, review, and worktree-aware tasking.

11. **Persistence and local filesystem layout**
   - The app is stateful on disk under `~/.codeany/`: settings, permissions, memory, sessions, skills, and plugins.
   - This makes the terminal agent portable but not stateless; user-specific behavior is driven by local files and project-root instructions.
   - The repository itself does not appear to be a server/client split; the primary deployment unit is the local CLI binary.

12. **Release and distribution**
   - `install.sh` supports quick install from GitHub.
   - `.github/workflows/release.yml` and `internal/version/version.go` suggest built-in release/version reporting and automated publishing.
   - `Makefile` likely supports build/test/release tasks, but the main architectural point is that the binary is intended for direct local installation and self-update.

13. **How data flows through the system**
   - User input enters via TUI or stdin.
   - CLI and slash-command routing determine whether the input becomes a chat turn, a tool/action request, or a configuration/session operation.
   - Session/config/context layers assemble local state and permissions.
   - The agent backend calls the model and any configured tools/MCP servers.
   - Results flow back through session state into the renderer, and may also be persisted to disk.

14. **Key architectural boundary to capture in a diagram**
   - Draw the app as a local terminal client with four major internal planes:
     - **Front end:** Bubble Tea TUI + pipe mode
     - **State:** session, memory, config, permissions
     - **Capabilities:** slash commands, skills, plugins, team/workflows, worktree helpers
     - **External integrations:** model API, MCP servers, filesystem/git, local disk persistence
   - That separation is the clearest way to represent the repo’s architecture accurately.

Main entry points: [`internal/tui/model.go`](https://github.com/codeany-ai/codeany/blob/main/internal/tui/model.go) (TUI model), [`internal/cli/root.go`](https://github.com/codeany-ai/codeany/blob/main/internal/cli/root.go) (Root cmd), [`internal/config/config.go`](https://github.com/codeany-ai/codeany/blob/main/internal/config/config.go) (Config), [`internal/session/session.go`](https://github.com/codeany-ai/codeany/blob/main/internal/session/session.go) (Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Front end"]
  node_node_main(("CLI entry<br/>entrypoint<br/>[main.go]"))
  node_node_root["Root cmd<br/>cli router<br/>[root.go]"]
  node_node_tui_model["TUI model<br/>bubble tea model<br/>[model.go]"]
  node_node_tui_input["Input<br/>[input.go]"]
  node_node_tui_render["Render<br/>tui view<br/>[render.go]"]
  node_node_pipe["Pipe mode<br/>stdin workflow<br/>[pipe.go]"]
  node_node_theme["Theme<br/>styling<br/>[theme.go]"]
  node_node_spinners["Spinners<br/>ui feedback<br/>[spinners.go]"]
end

subgraph group_group_state["State"]
  node_node_session[("Sessions<br/>conversation state<br/>[session.go]")]
  node_node_config["Config<br/>settings<br/>[config.go]"]
  node_node_permissions["Permissions<br/>policy<br/>[permissions.go]"]
  node_node_memory[("Memory<br/>local recall<br/>[memory.go]")]
  node_node_worktree["Worktree<br/>repo context<br/>[worktree.go]"]
end

subgraph group_group_capabilities["Capabilities"]
  node_node_slash["Slash router<br/>command router<br/>[slash.go]"]
  node_node_commands["Commands<br/>[commands.go]"]
  node_node_skills["Skills<br/>task prompts<br/>[skills.go]"]
  node_node_plugins["Plugins<br/>extensibility<br/>[plugins.go]"]
  node_node_team["Team flows<br/>agent workflows<br/>[team.go]"]
end

subgraph group_group_integrations["Integrations"]
  node_node_model_api[("Model API<br/>external service")]
  node_node_mcp["MCP servers<br/>external tools"]
  node_node_fs_git["FS and Git<br/>environment"]
  node_node_disk[("Local disk<br/>persistence")]
end

subgraph group_group_release["Release"]
  node_node_version["Version<br/>build metadata<br/>[version.go]"]
end

node_node_main -->|"starts"| node_node_root
node_node_root -->|"interactive"| node_node_tui_model
node_node_root -->|"pipe/print"| node_node_pipe
node_node_root -->|"version"| node_node_version
node_node_root -->|"loads"| node_node_config
node_node_tui_model -->|"reads input"| node_node_tui_input
node_node_tui_model -->|"renders"| node_node_tui_render
node_node_tui_model -->|"tracks"| node_node_session
node_node_tui_model -->|"routes commands"| node_node_slash
node_node_tui_model -->|"orchestrates"| node_node_team
node_node_pipe -->|"uses"| node_node_session
node_node_pipe -->|"calls"| node_node_model_api
node_node_slash -->|"dispatches"| node_node_commands
node_node_commands -->|"loads"| node_node_skills
node_node_commands -->|"extends"| node_node_plugins
node_node_team -->|"analyzes"| node_node_worktree
node_node_team -->|"coordinates"| node_node_model_api
node_node_session -->|"persists recall"| node_node_memory
node_node_session -->|"saves"| node_node_disk
node_node_config -->|"includes"| node_node_permissions
node_node_config -->|"configures"| node_node_mcp
node_node_config -->|"selects provider"| node_node_model_api
node_node_worktree -->|"reads"| node_node_fs_git
node_node_memory -->|"stores"| node_node_disk
node_node_skills -->|"loads"| node_node_disk
node_node_plugins -->|"loads"| node_node_disk
node_node_theme -->|"contains"| node_node_spinners
node_node_tui_render -->|"styles with"| node_node_theme
node_node_tui_render -->|"shows feedback"| node_node_spinners
node_node_tui_model -->|"generates"| node_node_model_api
node_node_tui_model -->|"tools"| node_node_mcp

click node_node_main "https://github.com/codeany-ai/codeany/blob/main/cmd/codeany/main.go"
click node_node_root "https://github.com/codeany-ai/codeany/blob/main/internal/cli/root.go"
click node_node_tui_model "https://github.com/codeany-ai/codeany/blob/main/internal/tui/model.go"
click node_node_tui_input "https://github.com/codeany-ai/codeany/blob/main/internal/tui/input.go"
click node_node_tui_render "https://github.com/codeany-ai/codeany/blob/main/internal/tui/render.go"
click node_node_pipe "https://github.com/codeany-ai/codeany/blob/main/internal/pipe/pipe.go"
click node_node_session "https://github.com/codeany-ai/codeany/blob/main/internal/session/session.go"
click node_node_config "https://github.com/codeany-ai/codeany/blob/main/internal/config/config.go"
click node_node_permissions "https://github.com/codeany-ai/codeany/blob/main/internal/config/permissions.go"
click node_node_memory "https://github.com/codeany-ai/codeany/blob/main/internal/memory/memory.go"
click node_node_worktree "https://github.com/codeany-ai/codeany/blob/main/internal/worktree/worktree.go"
click node_node_slash "https://github.com/codeany-ai/codeany/blob/main/internal/slash/slash.go"
click node_node_commands "https://github.com/codeany-ai/codeany/blob/main/internal/slash/commands.go"
click node_node_skills "https://github.com/codeany-ai/codeany/blob/main/internal/skills/skills.go"
click node_node_plugins "https://github.com/codeany-ai/codeany/blob/main/internal/plugins/plugins.go"
click node_node_team "https://github.com/codeany-ai/codeany/blob/main/internal/team/team.go"
click node_node_theme "https://github.com/codeany-ai/codeany/blob/main/internal/theme/theme.go"
click node_node_spinners "https://github.com/codeany-ai/codeany/blob/main/internal/theme/spinners.go"
click node_node_version "https://github.com/codeany-ai/codeany/blob/main/internal/version/version.go"

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_node_main,node_node_root,node_node_tui_model,node_node_tui_input,node_node_tui_render,node_node_pipe,node_node_theme,node_node_spinners toneBlue
class node_node_session,node_node_config,node_node_permissions,node_node_memory,node_node_worktree toneAmber
class node_node_slash,node_node_commands,node_node_skills,node_node_plugins,node_node_team toneMint
class node_node_model_api,node_node_mcp,node_node_fs_git,node_node_disk toneRose
class node_node_version toneIndigo
```

## Components

### Front end

Interactive and piped terminal entry points

- [CLI entry](https://github.com/codeany-ai/codeany/blob/main/cmd/codeany/main.go): entrypoint · Process startup and handoff to the command layer · `cmd/codeany/main.go`
- [Root cmd](https://github.com/codeany-ai/codeany/blob/main/internal/cli/root.go): cli router · Top-level parsing, mode selection, and command dispatch · `internal/cli/root.go`
- [TUI model](https://github.com/codeany-ai/codeany/blob/main/internal/tui/model.go): bubble tea model · Interactive chat loop and state machine · `internal/tui/model.go`
- [Input](https://github.com/codeany-ai/codeany/blob/main/internal/tui/input.go): tui input · Key handling and prompt input plumbing · `internal/tui/input.go`
- [Render](https://github.com/codeany-ai/codeany/blob/main/internal/tui/render.go): tui view · Conversation, tool output, and status presentation · `internal/tui/render.go`
- [Pipe mode](https://github.com/codeany-ai/codeany/blob/main/internal/pipe/pipe.go): stdin workflow · Non-interactive scripted input and print mode · `internal/pipe/pipe.go`
- [Theme](https://github.com/codeany-ai/codeany/blob/main/internal/theme/theme.go): styling · Visual styling and spinner presentation · `internal/theme/theme.go`
- [Spinners](https://github.com/codeany-ai/codeany/blob/main/internal/theme/spinners.go): ui feedback · Loading and progress affordances · `internal/theme/spinners.go`

### State

Local session, config, memory, and project context

- [Sessions](https://github.com/codeany-ai/codeany/blob/main/internal/session/session.go): conversation state · Turn history, resume state, and persisted session metadata · `internal/session/session.go`
- [Config](https://github.com/codeany-ai/codeany/blob/main/internal/config/config.go): settings · Global settings and runtime configuration assembly · `internal/config/config.go`
- [Permissions](https://github.com/codeany-ai/codeany/blob/main/internal/config/permissions.go): policy · Authorization and approval rules for agent actions · `internal/config/permissions.go`
- [Memory](https://github.com/codeany-ai/codeany/blob/main/internal/memory/memory.go): local recall · Long-lived remembered facts and project notes · `internal/memory/memory.go`
- [Worktree](https://github.com/codeany-ai/codeany/blob/main/internal/worktree/worktree.go): repo context · Filesystem and repository awareness for local tasks · `internal/worktree/worktree.go`

### Capabilities

Commands, skills, plugins, and task workflows

- [Slash router](https://github.com/codeany-ai/codeany/blob/main/internal/slash/slash.go): command router · Interactive command dispatch for slash actions · `internal/slash/slash.go`
- [Commands](https://github.com/codeany-ai/codeany/blob/main/internal/slash/commands.go): slash commands · Registered command set such as plan, review, test, and config · `internal/slash/commands.go`
- [Skills](https://github.com/codeany-ai/codeany/blob/main/internal/skills/skills.go): task prompts · Reusable markdown task instructions · `internal/skills/skills.go`
- [Plugins](https://github.com/codeany-ai/codeany/blob/main/internal/plugins/plugins.go): extensibility · Packaged capability bundles and integrations · `internal/plugins/plugins.go`
- [Team flows](https://github.com/codeany-ai/codeany/blob/main/internal/team/team.go): agent workflows · Higher-level orchestrated task behavior beyond basic chat · `internal/team/team.go`

### Integrations

Model, tool, filesystem, and local persistence boundaries

- **Model API**: external service · LLM provider accessed through API keys and base URLs
- **MCP servers**: external tools · Configured tool servers invoked by the agent
- **FS and Git**: environment · Local filesystem and git operations used by tasks and diffs
- **Local disk**: persistence · On-disk state under ~/.codeany for settings, sessions, memory, skills, and plugins

### Release

Versioning and distribution support

- [Version](https://github.com/codeany-ai/codeany/blob/main/internal/version/version.go): build metadata · Version reporting and release metadata · `internal/version/version.go`

## Connections

- CLI entry → Root cmd: starts · Executable enters the CLI router
- Root cmd → TUI model: interactive · Selects the Bubble Tea runtime
- Root cmd → Pipe mode: pipe/print · Selects stdin-driven scripting mode
- Root cmd → Version: version · Handles version and release reporting
- Root cmd → Config: loads · Builds runtime settings early
- TUI model → Input: reads input · Consumes keyboard and prompt events
- TUI model → Render: renders · Updates the terminal view
- TUI model → Sessions: tracks · Maintains active conversation state
- TUI model → Slash router: routes commands · Delegates slash-prefixed actions
- TUI model → Team flows: orchestrates · Runs higher-level task workflows
- Pipe mode → Sessions: uses · Reuses the same conversation/session layer
- Pipe mode → Model API: calls · Sends scripted prompts to the model backend
- Slash router → Commands: dispatches · Maps user commands to handlers
- Commands → Skills: loads · Some commands invoke reusable task instructions
- Commands → Plugins: extends · Commands expose plugin-backed capabilities
- Team flows → Worktree: analyzes · Uses repo context for task execution
- Team flows → Model API: coordinates · Drives model-backed workflows
- Sessions → Memory: persists recall · Normalizes long-lived remembered context
- Sessions → Local disk: saves · Writes session history and metadata locally
- Config → Permissions: includes · Configuration includes authorization policy
- Config → MCP servers: configures · Defines external tool servers and related settings
- Config → Model API: selects provider · Feeds API keys, base URLs, and model settings
- Worktree → FS and Git: reads · Inspects repository files and git state
- Memory → Local disk: stores · Reads and writes local memory files
- Skills → Local disk: loads · Skills are sourced from local markdown files
- Plugins → Local disk: loads · Plugin bundles are discovered from disk
- Theme → Spinners: contains · UI theme includes spinner affordances
- Render → Theme: styles with · Presentation layer uses theme primitives
- Render → Spinners: shows feedback · Displays busy and progress states
- TUI model → Model API: generates · Interactive chat ultimately calls the model backend
- TUI model → MCP servers: tools · Can invoke configured MCP tools
