# agoldian/claudenv architecture

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

- Interactive diagram: https://gitdiagram.com/agoldian/claudenv
- Repository: https://github.com/agoldian/claudenv

## Overview

claudenv sets up Claude Code in a project, then supports ongoing work through an autonomous improvement loop, configurable autonomy, memory, and an extensible skills harness. The main user flow starts at the CLI, detects the project stack, and generates project guidance and configuration. Separate CLI commands cover memory, decisions, canon, workspaces, connectors, health checks, and loop reporting. Edges reflect README statements and the shown source references; several subsystems are represented from documentation or the source index because their implementation excerpts were not provided.

Main entry points: [`bin/cli.js`](https://github.com/agoldian/claudenv/blob/main/bin/cli.js) (Command-line interface), [`src/loop.js`](https://github.com/agoldian/claudenv/blob/main/src/loop.js) (Improvement loop), [`src/memory-paths.js`](https://github.com/agoldian/claudenv/blob/main/src/memory-paths.js) (Memory path resolver), [`src/capabilities.js`](https://github.com/agoldian/claudenv/blob/main/src/capabilities.js) (Capability discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Project setup"]
  node_cli["Command-line interface<br/>[cli.js]"]
  node_detector["Stack detection<br/>[detector.js]"]
  node_generator["Guidance generation<br/>[generator.js]"]
  node_prompts["Setup prompts<br/>[prompts.js]"]
  node_validator["Guidance validation<br/>[validator.js]"]
  node_scaffold["Claude Code scaffold"]
  node_installer["Scaffold installation<br/>[installer.js]"]
end

subgraph group_loop["Autonomous work"]
  node_loopengine["Improvement loop<br/>[loop.js]"]
  node_report["Loop reporting<br/>[report.js]"]
  node_worktree["Isolated worktrees<br/>[worktree.js]"]
end

subgraph group_memory["Memory and decisions"]
  node_memorycli["Memory commands<br/>[memory.js]"]
  node_memorypaths["Memory path resolver<br/>[memory-paths.js]"]
  node_memorycontext["Loop memory context<br/>[memory-context.js]"]
  node_decisions["Decision records<br/>[decisions.js]"]
  node_canon["Personal canon<br/>[canon.js]"]
  node_regen["Memory index regeneration<br/>[regen-index.js]"]
  node_pythonbackend["Python memory backend<br/>[backend.py]"]
  node_pythonpaths["Python path resolver<br/>[paths.py]"]
end

subgraph group_harness["Extensible harness"]
  node_capabilities["Capability discovery<br/>[capabilities.js]"]
  node_skills["Skill registry and install<br/>[skills-registry.js]"]
  node_catalog["Bundled skill catalog<br/>[bundled-catalog.js]"]
  node_kimi["Browser automation bridge<br/>[kimi.js]"]
  node_sources["Data-source connectors<br/>[sources.js]"]
  node_workspaces["Workspace isolation<br/>[workspaces.js]"]
end

subgraph group_operations["Operations and safety"]
  node_profiles["Autonomy profiles<br/>[profiles.js]"]
  node_autonomy["Autonomy configuration<br/>[autonomy.js]"]
  node_hookgen["Hooks and safety config<br/>[hooks-gen.js]"]
  node_dispatcher["Hook dispatcher<br/>[dispatcher.js]"]
  node_doctor["Environment health checks<br/>[doctor.js]"]
end

node_user(("Project user"))
node_claude(("Claude Code"))

node_user -->|"runs commands"| node_cli
node_cli -->|"detects stack"| node_detector
node_cli -->|"starts setup"| node_prompts
node_cli -->|"generates guidance"| node_generator
node_cli -->|"validates output"| node_validator
node_generator -.->|"uses templates"| node_scaffold
node_cli -->|"installs scaffold"| node_installer
node_cli -->|"runs loop"| node_loopengine
node_loopengine -->|"invokes headless"| node_claude
node_cli -->|"reads reports"| node_report
node_loopengine -->|"isolates iterations"| node_worktree
node_loopengine -->|"builds prompt context"| node_memorycontext
node_memorycontext -->|"reads memory paths"| node_memorypaths
node_loopengine -->|"refreshes index"| node_regen
node_cli -->|"runs memory commands"| node_memorycli
node_memorycli -->|"resolves storage paths"| node_memorypaths
node_cli -->|"runs decision commands"| node_decisions
node_decisions -->|"resolves memory paths"| node_memorypaths
node_cli -->|"runs canon commands"| node_canon
node_canon -->|"resolves canon paths"| node_memorypaths
node_regen -.->|"uses memory layout"| node_memorypaths
node_pythonbackend -->|"resolves virtual paths"| node_pythonpaths
node_cli -->|"maps capabilities"| node_capabilities
node_capabilities -->|"checks available skills"| node_skills
node_capabilities -->|"checks bundled catalog"| node_catalog
node_capabilities -->|"checks browser bridge"| node_kimi
node_cli -->|"searches and installs"| node_skills
node_skills -->|"looks up bundled skills"| node_catalog
node_cli -->|"manages connectors"| node_sources
node_cli -->|"manages workspaces"| node_workspaces
node_cli -->|"selects profiles"| node_profiles
node_cli -->|"configures autonomy"| node_autonomy
node_autonomy -->|"uses profile settings"| node_profiles
node_autonomy -->|"generates safety config"| node_hookgen
node_hookgen -->|"reads credentials policy"| node_profiles
node_cli -->|"checks environment"| node_doctor
node_dispatcher -->|"dispatches index hook"| node_regen

click node_cli "https://github.com/agoldian/claudenv/blob/main/bin/cli.js"
click node_detector "https://github.com/agoldian/claudenv/blob/main/src/detector.js"
click node_generator "https://github.com/agoldian/claudenv/blob/main/src/generator.js"
click node_prompts "https://github.com/agoldian/claudenv/blob/main/src/prompts.js"
click node_validator "https://github.com/agoldian/claudenv/blob/main/src/validator.js"
click node_scaffold "https://github.com/agoldian/claudenv/tree/main/scaffold"
click node_loopengine "https://github.com/agoldian/claudenv/blob/main/src/loop.js"
click node_report "https://github.com/agoldian/claudenv/blob/main/src/report.js"
click node_worktree "https://github.com/agoldian/claudenv/blob/main/src/worktree.js"
click node_memorycli "https://github.com/agoldian/claudenv/blob/main/src/memory.js"
click node_memorypaths "https://github.com/agoldian/claudenv/blob/main/src/memory-paths.js"
click node_memorycontext "https://github.com/agoldian/claudenv/blob/main/src/memory-context.js"
click node_decisions "https://github.com/agoldian/claudenv/blob/main/src/decisions.js"
click node_canon "https://github.com/agoldian/claudenv/blob/main/src/canon.js"
click node_regen "https://github.com/agoldian/claudenv/blob/main/src/hooks/regen-index.js"
click node_pythonbackend "https://github.com/agoldian/claudenv/blob/main/python/claudenv_memory/backend.py"
click node_pythonpaths "https://github.com/agoldian/claudenv/blob/main/python/claudenv_memory/paths.py"
click node_capabilities "https://github.com/agoldian/claudenv/blob/main/src/capabilities.js"
click node_skills "https://github.com/agoldian/claudenv/blob/main/src/skills-registry.js"
click node_catalog "https://github.com/agoldian/claudenv/blob/main/src/bundled-catalog.js"
click node_kimi "https://github.com/agoldian/claudenv/blob/main/src/kimi.js"
click node_sources "https://github.com/agoldian/claudenv/blob/main/src/sources.js"
click node_workspaces "https://github.com/agoldian/claudenv/blob/main/src/workspaces.js"
click node_profiles "https://github.com/agoldian/claudenv/blob/main/src/profiles.js"
click node_autonomy "https://github.com/agoldian/claudenv/blob/main/src/autonomy.js"
click node_hookgen "https://github.com/agoldian/claudenv/blob/main/src/hooks-gen.js"
click node_dispatcher "https://github.com/agoldian/claudenv/blob/main/src/hooks/dispatcher.js"
click node_doctor "https://github.com/agoldian/claudenv/blob/main/src/doctor.js"
click node_installer "https://github.com/agoldian/claudenv/blob/main/src/installer.js"

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_detector,node_generator,node_prompts,node_validator,node_scaffold,node_installer,node_user toneBlue
class node_loopengine,node_report,node_worktree toneAmber
class node_memorycli,node_memorypaths,node_memorycontext,node_decisions,node_canon,node_regen,node_pythonbackend,node_pythonpaths toneMint
class node_capabilities,node_skills,node_catalog,node_kimi,node_sources,node_workspaces toneRose
class node_profiles,node_autonomy,node_hookgen,node_dispatcher,node_doctor,node_claude toneIndigo
```

## Components

### Project setup

- [Command-line interface](https://github.com/agoldian/claudenv/blob/main/bin/cli.js): `bin/cli.js`
- [Stack detection](https://github.com/agoldian/claudenv/blob/main/src/detector.js): `src/detector.js`
- [Guidance generation](https://github.com/agoldian/claudenv/blob/main/src/generator.js): `src/generator.js`
- [Setup prompts](https://github.com/agoldian/claudenv/blob/main/src/prompts.js): `src/prompts.js`
- [Guidance validation](https://github.com/agoldian/claudenv/blob/main/src/validator.js): `src/validator.js`
- [Claude Code scaffold](https://github.com/agoldian/claudenv/tree/main/scaffold): `scaffold`
- [Scaffold installation](https://github.com/agoldian/claudenv/blob/main/src/installer.js): `src/installer.js`

### Autonomous work

- [Improvement loop](https://github.com/agoldian/claudenv/blob/main/src/loop.js): `src/loop.js`
- [Loop reporting](https://github.com/agoldian/claudenv/blob/main/src/report.js): `src/report.js`
- [Isolated worktrees](https://github.com/agoldian/claudenv/blob/main/src/worktree.js): `src/worktree.js`

### Memory and decisions

- [Memory commands](https://github.com/agoldian/claudenv/blob/main/src/memory.js): `src/memory.js`
- [Memory path resolver](https://github.com/agoldian/claudenv/blob/main/src/memory-paths.js): `src/memory-paths.js`
- [Loop memory context](https://github.com/agoldian/claudenv/blob/main/src/memory-context.js): `src/memory-context.js`
- [Decision records](https://github.com/agoldian/claudenv/blob/main/src/decisions.js): `src/decisions.js`
- [Personal canon](https://github.com/agoldian/claudenv/blob/main/src/canon.js): `src/canon.js`
- [Memory index regeneration](https://github.com/agoldian/claudenv/blob/main/src/hooks/regen-index.js): `src/hooks/regen-index.js`
- [Python memory backend](https://github.com/agoldian/claudenv/blob/main/python/claudenv_memory/backend.py): `python/claudenv_memory/backend.py`
- [Python path resolver](https://github.com/agoldian/claudenv/blob/main/python/claudenv_memory/paths.py): `python/claudenv_memory/paths.py`

### Extensible harness

- [Capability discovery](https://github.com/agoldian/claudenv/blob/main/src/capabilities.js): `src/capabilities.js`
- [Skill registry and install](https://github.com/agoldian/claudenv/blob/main/src/skills-registry.js): `src/skills-registry.js`
- [Bundled skill catalog](https://github.com/agoldian/claudenv/blob/main/src/bundled-catalog.js): `src/bundled-catalog.js`
- [Browser automation bridge](https://github.com/agoldian/claudenv/blob/main/src/kimi.js): `src/kimi.js`
- [Data-source connectors](https://github.com/agoldian/claudenv/blob/main/src/sources.js): `src/sources.js`
- [Workspace isolation](https://github.com/agoldian/claudenv/blob/main/src/workspaces.js): `src/workspaces.js`

### Operations and safety

- [Autonomy profiles](https://github.com/agoldian/claudenv/blob/main/src/profiles.js): `src/profiles.js`
- [Autonomy configuration](https://github.com/agoldian/claudenv/blob/main/src/autonomy.js): `src/autonomy.js`
- [Hooks and safety config](https://github.com/agoldian/claudenv/blob/main/src/hooks-gen.js): `src/hooks-gen.js`
- [Hook dispatcher](https://github.com/agoldian/claudenv/blob/main/src/hooks/dispatcher.js): `src/hooks/dispatcher.js`
- [Environment health checks](https://github.com/agoldian/claudenv/blob/main/src/doctor.js): `src/doctor.js`

### Other components

- **Project user**
- **Claude Code**

## Connections

- Project user → Command-line interface: runs commands (evidence: `README.md`)
- Command-line interface → Stack detection: detects stack (evidence: `bin/cli.js`)
- Command-line interface → Setup prompts: starts setup (evidence: `bin/cli.js`)
- Command-line interface → Guidance generation: generates guidance (evidence: `bin/cli.js`)
- Command-line interface → Guidance validation: validates output (evidence: `bin/cli.js`)
- Guidance generation → Claude Code scaffold: uses templates
- Command-line interface → Scaffold installation: installs scaffold (evidence: `bin/cli.js`)
- Command-line interface → Improvement loop: runs loop (evidence: `bin/cli.js`)
- Improvement loop → Claude Code: invokes headless (evidence: `README.md`)
- Command-line interface → Loop reporting: reads reports (evidence: `bin/cli.js`)
- Improvement loop → Isolated worktrees: isolates iterations (evidence: `src/loop.js`)
- Improvement loop → Loop memory context: builds prompt context (evidence: `src/loop.js`)
- Loop memory context → Memory path resolver: reads memory paths (evidence: `src/memory-context.js`)
- Improvement loop → Memory index regeneration: refreshes index (evidence: `src/loop.js`)
- Command-line interface → Memory commands: runs memory commands (evidence: `bin/cli.js`)
- Memory commands → Memory path resolver: resolves storage paths (evidence: `src/memory.js`)
- Command-line interface → Decision records: runs decision commands (evidence: `bin/cli.js`)
- Decision records → Memory path resolver: resolves memory paths (evidence: `src/decisions.js`)
- Command-line interface → Personal canon: runs canon commands (evidence: `bin/cli.js`)
- Personal canon → Memory path resolver: resolves canon paths (evidence: `src/canon.js`)
- Memory index regeneration → Memory path resolver: uses memory layout
- Python memory backend → Python path resolver: resolves virtual paths (evidence: `python/claudenv_memory/backend.py`)
- Command-line interface → Capability discovery: maps capabilities (evidence: `bin/cli.js`)
- Capability discovery → Skill registry and install: checks available skills (evidence: `src/capabilities.js`)
- Capability discovery → Bundled skill catalog: checks bundled catalog (evidence: `src/capabilities.js`)
- Capability discovery → Browser automation bridge: checks browser bridge (evidence: `src/capabilities.js`)
- Command-line interface → Skill registry and install: searches and installs (evidence: `bin/cli.js`)
- Skill registry and install → Bundled skill catalog: looks up bundled skills (evidence: `src/skills-registry.js`)
- Command-line interface → Data-source connectors: manages connectors (evidence: `bin/cli.js`)
- Command-line interface → Workspace isolation: manages workspaces (evidence: `bin/cli.js`)
- Command-line interface → Autonomy profiles: selects profiles (evidence: `bin/cli.js`)
- Command-line interface → Autonomy configuration: configures autonomy (evidence: `bin/cli.js`)
- Autonomy configuration → Autonomy profiles: uses profile settings (evidence: `src/autonomy.js`)
- Autonomy configuration → Hooks and safety config: generates safety config (evidence: `src/autonomy.js`)
- Hooks and safety config → Autonomy profiles: reads credentials policy (evidence: `src/hooks-gen.js`)
- Command-line interface → Environment health checks: checks environment (evidence: `bin/cli.js`)
- Hook dispatcher → Memory index regeneration: dispatches index hook (evidence: `src/hooks/dispatcher.js`)
