How codeany-ai/codeany works
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: model.go TUI model · root.go Root cmd · config.go Config · session.go Sessions
Components 23
Front end
Interactive and piped terminal entry points
- CLI entry · Process startup and handoff to the command layer
cmd/codeany/main.go - Root cmd · Top-level parsing, mode selection, and command dispatch
internal/cli/root.go - TUI model · Interactive chat loop and state machine
internal/tui/model.go - Input · Key handling and prompt input plumbing
internal/tui/input.go - Render · Conversation, tool output, and status presentation
internal/tui/render.go - Pipe mode · Non-interactive scripted input and print mode
internal/pipe/pipe.go - Theme · Visual styling and spinner presentation
internal/theme/theme.go - Spinners · Loading and progress affordances
internal/theme/spinners.go
State
Local session, config, memory, and project context
- Sessions · Turn history, resume state, and persisted session metadata
internal/session/session.go - Config · Global settings and runtime configuration assembly
internal/config/config.go - Permissions · Authorization and approval rules for agent actions
internal/config/permissions.go - Memory · Long-lived remembered facts and project notes
internal/memory/memory.go - Worktree · Filesystem and repository awareness for local tasks
internal/worktree/worktree.go
Capabilities
Commands, skills, plugins, and task workflows
- Slash router · Interactive command dispatch for slash actions
internal/slash/slash.go - Commands · Registered command set such as plan, review, test, and config
internal/slash/commands.go - Skills · Reusable markdown task instructions
internal/skills/skills.go - Plugins · Packaged capability bundles and integrations
internal/plugins/plugins.go - Team flows · Higher-level orchestrated task behavior beyond basic chat
internal/team/team.go
Integrations
Model, tool, filesystem, and local persistence boundaries
- Model API · LLM provider accessed through API keys and base URLs
- MCP servers · Configured tool servers invoked by the agent
- FS and Git · Local filesystem and git operations used by tasks and diffs
- Local disk · On-disk state under ~/.codeany for settings, sessions, memory, skills, and plugins
Release
Versioning and distribution support
- Version · Version reporting and release metadata
internal/version/version.go
Connections 31
- 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