# svtoo/atk architecture

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

- Interactive diagram: https://gitdiagram.com/svtoo/atk
- Repository: https://github.com/svtoo/atk
- Video tour (about a minute): https://gitdiagram.com/svtoo/atk/video

## Overview

ATK is a CLI plugin manager for discovering, installing, configuring, and operating AI-development tools, then connecting their MCP servers and skills to coding agents. The main workflow is search or choose a plugin, add it to git-backed ATK Home, configure its environment, and plug it into selected agents; lifecycle commands then start, inspect, upgrade, or remove it. The graph includes documented capabilities whose command implementations were not sampled; links to those modules are intentionally limited to documented CLI dispatch. The MCP/agent wiring is supported by sampled source.

Main entry points: [`src/atk/cli.py`](https://github.com/svtoo/atk/blob/main/src/atk/cli.py) (ATK CLI), [`src/atk/add.py`](https://github.com/svtoo/atk/blob/main/src/atk/add.py) (Plugin add), [`src/atk/manifest_schema.py`](https://github.com/svtoo/atk/blob/main/src/atk/manifest_schema.py) (Manifest), [`src/atk/lifecycle.py`](https://github.com/svtoo/atk/blob/main/src/atk/lifecycle.py) (Lifecycle runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI Interface"]
  node_cli["ATK CLI<br/>[cli.py]"]
  node_search["Registry search<br/>[search.py]"]
end

subgraph group_plugin_ops["Plugin Operations"]
  node_add["Plugin add<br/>[add.py]"]
  node_setup["Environment setup<br/>[setup.py]"]
  node_lifecycle_cli["Lifecycle commands<br/>[lifecycle.py]"]
  node_lifecycle["Lifecycle runner<br/>[lifecycle.py]"]
  node_status["Status reporting<br/>[status.py]"]
  node_upgrade["Plugin upgrade<br/>[upgrade.py]"]
  node_remove["Plugin removal<br/>[remove.py]"]
end

subgraph group_home_registry["Home and Registry"]
  node_manifest["Manifest<br/>[manifest_schema.py]"]
  node_home["ATK Home<br/>[home.py]"]
  node_git["Git operations<br/>[git.py]"]
  node_registry["Registry access<br/>[registry.py]"]
  node_plugin_schema["Plugin definitions<br/>[plugin_schema.py]"]
end

subgraph group_agent_integration["Agent Integration"]
  node_mcp_command["Plug orchestration<br/>[plug.py]"]
  node_mcp["MCP configuration<br/>[mcp.py]"]
  node_agent_runners["Agent adapters<br/>[mcp.py]"]
  node_skill_adapters["Skill adapters"]
end

node_developer(("Developer"))
node_coding_agents(("Coding agents"))
node_plugin_services["Plugin services"]
node_registry_service["ATK registry"]

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches search"| node_search
node_cli -->|"dispatches add"| node_add
node_cli -->|"dispatches setup"| node_setup
node_cli -->|"dispatches lifecycle"| node_lifecycle_cli
node_cli -->|"dispatches status"| node_status
node_cli -->|"dispatches upgrade"| node_upgrade
node_cli -->|"dispatches remove"| node_remove
node_cli -->|"dispatches plug"| node_mcp_command
node_search -->|"fetches index"| node_registry
node_search -->|"reads installed set"| node_manifest
node_registry -->|"fetches registry"| node_registry_service
node_add -->|"fetches plugin"| node_registry
node_add -->|"loads definition"| node_plugin_schema
node_add -->|"records plugin"| node_manifest
node_add -->|"installs into"| node_home
node_add -->|"fetches source"| node_git
node_setup -->|"reads requirements"| node_plugin_schema
node_setup -->|"configures plugin"| node_home
node_lifecycle_cli -->|"runs commands"| node_lifecycle
node_lifecycle -->|"reads plugins"| node_manifest
node_lifecycle -->|"loads lifecycle"| node_plugin_schema
node_lifecycle -->|"runs lifecycle"| node_plugin_services
node_status -->|"reads plugins"| node_manifest
node_status -->|"checks state"| node_plugin_services
node_upgrade -->|"reads sources"| node_manifest
node_upgrade -->|"fetches updates"| node_git
node_remove -->|"runs uninstall"| node_lifecycle
node_remove -->|"updates manifest"| node_manifest
node_mcp_command -->|"resolves config"| node_mcp
node_mcp_command -->|"registers MCP"| node_agent_runners
node_mcp_command -->|"injects skills"| node_skill_adapters
node_agent_runners -->|"configures agents"| node_coding_agents
node_skill_adapters -->|"writes skill context"| node_coding_agents
node_mcp -->|"reads MCP definition"| node_plugin_schema
node_mcp -->|"resolves plugin files"| node_home

click node_cli "https://github.com/svtoo/atk/blob/main/src/atk/cli.py"
click node_search "https://github.com/svtoo/atk/blob/main/src/atk/commands/search.py"
click node_add "https://github.com/svtoo/atk/blob/main/src/atk/add.py"
click node_setup "https://github.com/svtoo/atk/blob/main/src/atk/setup.py"
click node_lifecycle_cli "https://github.com/svtoo/atk/blob/main/src/atk/commands/lifecycle.py"
click node_lifecycle "https://github.com/svtoo/atk/blob/main/src/atk/lifecycle.py"
click node_status "https://github.com/svtoo/atk/blob/main/src/atk/commands/status.py"
click node_upgrade "https://github.com/svtoo/atk/blob/main/src/atk/upgrade.py"
click node_remove "https://github.com/svtoo/atk/blob/main/src/atk/remove.py"
click node_manifest "https://github.com/svtoo/atk/blob/main/src/atk/manifest_schema.py"
click node_home "https://github.com/svtoo/atk/blob/main/src/atk/home.py"
click node_git "https://github.com/svtoo/atk/blob/main/src/atk/git.py"
click node_registry "https://github.com/svtoo/atk/blob/main/src/atk/registry.py"
click node_plugin_schema "https://github.com/svtoo/atk/blob/main/src/atk/plugin_schema.py"
click node_mcp_command "https://github.com/svtoo/atk/blob/main/src/atk/commands/plug.py"
click node_mcp "https://github.com/svtoo/atk/blob/main/src/atk/mcp.py"
click node_agent_runners "https://github.com/svtoo/atk/blob/main/src/atk/commands/mcp.py"
click node_skill_adapters "https://github.com/svtoo/atk/tree/main/src/atk/agents"

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_search toneBlue
class node_add,node_setup,node_lifecycle_cli,node_lifecycle,node_status,node_upgrade,node_remove toneAmber
class node_manifest,node_home,node_git,node_registry,node_plugin_schema toneMint
class node_mcp_command,node_mcp,node_agent_runners,node_skill_adapters toneRose
class node_developer,node_coding_agents,node_plugin_services,node_registry_service toneIndigo
```

## Components

### CLI Interface

- [ATK CLI](https://github.com/svtoo/atk/blob/main/src/atk/cli.py): `src/atk/cli.py`
- [Registry search](https://github.com/svtoo/atk/blob/main/src/atk/commands/search.py): `src/atk/commands/search.py`

### Plugin Operations

- [Plugin add](https://github.com/svtoo/atk/blob/main/src/atk/add.py): `src/atk/add.py`
- [Environment setup](https://github.com/svtoo/atk/blob/main/src/atk/setup.py): `src/atk/setup.py`
- [Lifecycle commands](https://github.com/svtoo/atk/blob/main/src/atk/commands/lifecycle.py): `src/atk/commands/lifecycle.py`
- [Lifecycle runner](https://github.com/svtoo/atk/blob/main/src/atk/lifecycle.py): `src/atk/lifecycle.py`
- [Status reporting](https://github.com/svtoo/atk/blob/main/src/atk/commands/status.py): `src/atk/commands/status.py`
- [Plugin upgrade](https://github.com/svtoo/atk/blob/main/src/atk/upgrade.py): `src/atk/upgrade.py`
- [Plugin removal](https://github.com/svtoo/atk/blob/main/src/atk/remove.py): `src/atk/remove.py`

### Home and Registry

- [Manifest](https://github.com/svtoo/atk/blob/main/src/atk/manifest_schema.py): `src/atk/manifest_schema.py`
- [ATK Home](https://github.com/svtoo/atk/blob/main/src/atk/home.py): `src/atk/home.py`
- [Git operations](https://github.com/svtoo/atk/blob/main/src/atk/git.py): `src/atk/git.py`
- [Registry access](https://github.com/svtoo/atk/blob/main/src/atk/registry.py): `src/atk/registry.py`
- [Plugin definitions](https://github.com/svtoo/atk/blob/main/src/atk/plugin_schema.py): `src/atk/plugin_schema.py`

### Agent Integration

- [Plug orchestration](https://github.com/svtoo/atk/blob/main/src/atk/commands/plug.py): `src/atk/commands/plug.py`
- [MCP configuration](https://github.com/svtoo/atk/blob/main/src/atk/mcp.py): `src/atk/mcp.py`
- [Agent adapters](https://github.com/svtoo/atk/blob/main/src/atk/commands/mcp.py): `src/atk/commands/mcp.py`
- [Skill adapters](https://github.com/svtoo/atk/tree/main/src/atk/agents): `src/atk/agents`

### Other components

- **Developer**
- **Coding agents**
- **Plugin services**
- **ATK registry**

## Connections

- Developer → ATK CLI: runs commands
- ATK CLI → Registry search: dispatches search
- ATK CLI → Plugin add: dispatches add
- ATK CLI → Environment setup: dispatches setup
- ATK CLI → Lifecycle commands: dispatches lifecycle
- ATK CLI → Status reporting: dispatches status
- ATK CLI → Plugin upgrade: dispatches upgrade
- ATK CLI → Plugin removal: dispatches remove
- ATK CLI → Plug orchestration: dispatches plug
- Registry search → Registry access: fetches index
- Registry search → Manifest: reads installed set
- Registry access → ATK registry: fetches registry
- Plugin add → Registry access: fetches plugin
- Plugin add → Plugin definitions: loads definition
- Plugin add → Manifest: records plugin
- Plugin add → ATK Home: installs into
- Plugin add → Git operations: fetches source
- Environment setup → Plugin definitions: reads requirements
- Environment setup → ATK Home: configures plugin
- Lifecycle commands → Lifecycle runner: runs commands
- Lifecycle runner → Manifest: reads plugins
- Lifecycle runner → Plugin definitions: loads lifecycle
- Lifecycle runner → Plugin services: runs lifecycle
- Status reporting → Manifest: reads plugins
- Status reporting → Plugin services: checks state
- Plugin upgrade → Manifest: reads sources
- Plugin upgrade → Git operations: fetches updates
- Plugin removal → Lifecycle runner: runs uninstall
- Plugin removal → Manifest: updates manifest
- Plug orchestration → MCP configuration: resolves config
- Plug orchestration → Agent adapters: registers MCP
- Plug orchestration → Skill adapters: injects skills
- Agent adapters → Coding agents: configures agents
- Skill adapters → Coding agents: writes skill context
- MCP configuration → Plugin definitions: reads MCP definition
- MCP configuration → ATK Home: resolves plugin files