# ob-labs/agentseek architecture

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

- Interactive diagram: https://gitdiagram.com/ob-labs/agentseek
- Repository: https://github.com/ob-labs/agentseek

## Overview

AgentSeek is a local, template-first lifecycle CLI for creating editable agent applications, then inspecting, configuring, checking, running, observing, and iterating on them. Its primary path starts with template discovery and creation; the generated project owns its runtime and integrations, while AgentSeek provides a stable lifecycle interface. The README documents the locked template catalog and lifecycle stages. Source excerpts are limited, so some CLI-to-subsystem links are documented rather than verified from implementation; the graph does not map template internals or unsampled integrations.

Main entry points: [`src/agentseek/cli/commands/create.py`](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/create.py) (Create project), [`src/agentseek/cli/commands/info.py`](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/info.py) (Inspect project), [`src/agentseek/cli/commands/doctor.py`](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/doctor.py) (Observe lifecycle), [`templates/deepagents/research/{{cookiecutter.project_slug}}`](https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D) (Edit and iterate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Lifecycle CLI"]
  node_discover["Discover templates<br/>[create.py]"]
  node_create["Create project<br/>[create.py]"]
  node_inspect["Inspect project<br/>[info.py]"]
  node_check["Check readiness<br/>[doctor.py]"]
  node_run["Run development stack<br/>[dev.py]"]
  node_observe["Observe lifecycle<br/>[doctor.py]"]
  node_tasks["Setup tasks<br/>[task.py]"]
  node_json_contract["Machine JSON contract<br/>[json_output.py]"]
end

subgraph group_catalog["Template Catalog"]
  node_catalog_service[("Locked template catalog")]
  node_template_sources["Template sources"]
end

subgraph group_project["Generated Project"]
  node_configure["Configure project"]
  node_iterate["Edit and iterate"]
  node_generated_app["Editable application"]
  node_lifecycle_contract["Lifecycle contract<br/>[authored.py]"]
end

subgraph group_internal["CLI Internals"]
  node_lifecycle_safety["Lifecycle safety<br/>[safety.py]"]
end

node_user(("Developer"))

node_user -->|"selects goal"| node_discover
node_discover -->|"lists templates"| node_catalog_service
node_user -->|"requests scaffold"| node_create
node_create -->|"fetches locked content"| node_catalog_service
node_catalog_service -->|"provides templates"| node_template_sources
node_create -->|"renders project"| node_generated_app
node_user -->|"inspects entry points"| node_inspect
node_inspect -->|"reads declarations"| node_lifecycle_contract
node_user -->|"sets credentials"| node_configure
node_user -->|"runs setup tasks"| node_tasks
node_user -->|"checks readiness"| node_check
node_user -->|"starts local stack"| node_run
node_user -->|"checks live state"| node_observe
node_observe -->|"emits machine output"| node_json_contract
node_user -->|"edits project"| node_iterate
node_iterate -->|"returns to inspection"| node_inspect
node_lifecycle_contract -->|"uses safety checks"| node_lifecycle_safety

click node_discover "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/create.py"
click node_create "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/create.py"
click node_inspect "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/info.py"
click node_configure "https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D"
click node_check "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/doctor.py"
click node_run "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/dev.py"
click node_observe "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/doctor.py"
click node_iterate "https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D"
click node_tasks "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/task.py"
click node_template_sources "https://github.com/ob-labs/agentseek/tree/main/templates"
click node_generated_app "https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D"
click node_lifecycle_contract "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/authored.py"
click node_json_contract "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/json_output.py"
click node_lifecycle_safety "https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/safety.py"

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_discover,node_create,node_inspect,node_check,node_run,node_observe,node_tasks,node_json_contract toneBlue
class node_catalog_service,node_template_sources toneAmber
class node_configure,node_iterate,node_generated_app,node_lifecycle_contract toneMint
class node_lifecycle_safety toneRose
class node_user toneIndigo
```

## Components

### Lifecycle CLI

- [Discover templates](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/create.py): `src/agentseek/cli/commands/create.py`
- [Create project](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/create.py): `src/agentseek/cli/commands/create.py`
- [Inspect project](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/info.py): `src/agentseek/cli/commands/info.py`
- [Check readiness](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/doctor.py): `src/agentseek/cli/commands/doctor.py`
- [Run development stack](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/dev.py): `src/agentseek/cli/commands/dev.py`
- [Observe lifecycle](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/doctor.py): `src/agentseek/cli/commands/doctor.py`
- [Setup tasks](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/commands/task.py): `src/agentseek/cli/commands/task.py`
- [Machine JSON contract](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/json_output.py): `src/agentseek/cli/lifecycle/json_output.py`

### Template Catalog

- **Locked template catalog**
- [Template sources](https://github.com/ob-labs/agentseek/tree/main/templates): `templates`

### Generated Project

- [Configure project](https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D): `templates/deepagents/research/{{cookiecutter.project_slug}}`
- [Edit and iterate](https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D): `templates/deepagents/research/{{cookiecutter.project_slug}}`
- [Editable application](https://github.com/ob-labs/agentseek/tree/main/templates/deepagents/research/%7B%7Bcookiecutter.project_slug%7D%7D): `templates/deepagents/research/{{cookiecutter.project_slug}}`
- [Lifecycle contract](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/authored.py): `src/agentseek/cli/lifecycle/authored.py`

### CLI Internals

- [Lifecycle safety](https://github.com/ob-labs/agentseek/blob/main/src/agentseek/cli/lifecycle/safety.py): `src/agentseek/cli/lifecycle/safety.py`

### Other components

- **Developer**

## Connections

- Developer → Discover templates: selects goal (evidence: `README.md`)
- Discover templates → Locked template catalog: lists templates (evidence: `README.md`)
- Developer → Create project: requests scaffold (evidence: `README.md`)
- Create project → Locked template catalog: fetches locked content (evidence: `README.md`)
- Locked template catalog → Template sources: provides templates (evidence: `README.md`)
- Create project → Editable application: renders project (evidence: `README.md`)
- Developer → Inspect project: inspects entry points (evidence: `README.md`)
- Inspect project → Lifecycle contract: reads declarations (evidence: `README.md`)
- Developer → Configure project: sets credentials (evidence: `README.md`)
- Developer → Setup tasks: runs setup tasks (evidence: `README.md`)
- Developer → Check readiness: checks readiness (evidence: `README.md`)
- Developer → Run development stack: starts local stack (evidence: `README.md`)
- Developer → Observe lifecycle: checks live state (evidence: `README.md`)
- Observe lifecycle → Machine JSON contract: emits machine output (evidence: `README.md`)
- Developer → Edit and iterate: edits project (evidence: `README.md`)
- Edit and iterate → Inspect project: returns to inspection (evidence: `README.md`)
- Lifecycle contract → Lifecycle safety: uses safety checks (evidence: `src/agentseek/cli/lifecycle/authored.py`)