# sagnnik/ness-agent architecture

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

- Interactive diagram: https://gitdiagram.com/sagnnik/ness-agent
- Repository: https://github.com/sagnnik/ness-agent

## Overview

Ness Agent is a Python coding-agent harness exposed both as an embeddable SDK and as the Ness terminal CLI. The main workflow is a user prompt entering the CLI, becoming a coding session, and running through the SDK session/graph loop to a model response and tool activity. The README also identifies permissions, memory, skills, MCP, compaction, reflection, tracing, plan/act modes, and worktrees as product capabilities. Several subsystem links are documented but their internal wiring was not sampled, so the graph omits uncertain call edges.

Main entry points: [`src/ness_cli/tui/main.py`](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/tui/main.py) (CLI entry), [`src/ness_agent/session.py`](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/session.py) (SDK session), [`src/ness_agent/graph/builder.py`](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/graph/builder.py) (Agent graph), [`src/ness_agent/tools`](https://github.com/sagnnik/ness-agent/tree/main/src/ness_agent/tools) (Built-in tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Ness CLI"]
  node_entry["CLI entry<br/>[main.py]"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_headless["Headless runner<br/>[headless.py]"]
  node_factory["Session factory<br/>[factory.py]"]
  node_coding["Coding session<br/>[coding_session.py]"]
  node_worktrees["Git worktrees<br/>[worktree.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_agent["NessAgent<br/>[agent.py]"]
  node_session["SDK session<br/>[session.py]"]
  node_graph["Agent graph<br/>[builder.py]"]
  node_persistence[("Thread persistence<br/>[persistence.py]")]
end

subgraph group_features["Agent Capabilities"]
  node_tools["Built-in tools"]
  node_permissions["Tool permissions<br/>[permissions.py]"]
  node_context["Prompt context"]
  node_memory["Memory<br/>[memory.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_mcp_runtime["MCP runtime<br/>[mcp.py]"]
  node_lifecycle["Turn lifecycle<br/>[compaction.py]"]
  node_reflection["Reflection<br/>[reflection.py]"]
  node_tracing["Tracing<br/>[tracer.py]"]
end

subgraph group_integrations["Providers &amp; Integrations"]
  node_providers["Provider registry<br/>[registry.py]"]
  node_provider_models["Provider adapters"]
  node_mcp_cli["Project MCP<br/>[mcp_manager.py]"]
end

node_user(("Engineer"))
node_model_service(("Chat model"))
node_mcp_servers{{"MCP servers"}}
node_git[("Git repository")]

node_user -->|"starts session"| node_entry
node_entry -->|"opens UI"| node_tui
node_entry -->|"runs prompt"| node_headless
node_entry -->|"builds session"| node_factory
node_tui -->|"handles turns"| node_coding
node_headless -->|"runs turns"| node_coding
node_factory -->|"creates"| node_coding
node_coding -->|"uses SDK"| node_agent
node_agent -->|"creates"| node_session
node_session -->|"runs"| node_graph
node_graph -->|"requests inference"| node_model_service
node_graph -->|"dispatches tools"| node_tools
node_graph -->|"checkpoints state"| node_persistence
node_providers -->|"resolves adapter"| node_provider_models
node_factory -->|"configures model"| node_providers
node_session -->|"assembles prompt"| node_context
node_session -->|"manages context"| node_lifecycle
node_session -->|"finalizes turns"| node_reflection
node_tools -->|"checks access"| node_permissions
node_tools -.->|"accesses memory"| node_memory
node_tools -.->|"uses skills"| node_skills
node_entry -->|"configures MCP"| node_mcp_cli
node_mcp_cli -->|"coordinates"| node_mcp_runtime
node_mcp_runtime -.->|"connects tools"| node_mcp_servers
node_session -.->|"emits traces"| node_tracing
node_entry -->|"prepares worktree"| node_worktrees
node_worktrees -->|"creates worktree"| node_git

click node_entry "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/tui/main.py"
click node_tui "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/tui/app.py"
click node_headless "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/headless.py"
click node_factory "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/factory.py"
click node_coding "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/coding_session.py"
click node_providers "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/provider/registry.py"
click node_provider_models "https://github.com/sagnnik/ness-agent/tree/main/src/ness_cli/provider"
click node_agent "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/agent.py"
click node_session "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/session.py"
click node_graph "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/graph/builder.py"
click node_tools "https://github.com/sagnnik/ness-agent/tree/main/src/ness_agent/tools"
click node_permissions "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/permissions.py"
click node_context "https://github.com/sagnnik/ness-agent/tree/main/src/ness_agent/context"
click node_memory "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/memory.py"
click node_skills "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/skills.py"
click node_persistence "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/persistence.py"
click node_mcp_cli "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/mcp_manager.py"
click node_mcp_runtime "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/mcp.py"
click node_lifecycle "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/compaction.py"
click node_reflection "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/reflection.py"
click node_tracing "https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/tracing/tracer.py"
click node_worktrees "https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/worktree.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_entry,node_tui,node_headless,node_factory,node_coding,node_worktrees toneBlue
class node_agent,node_session,node_graph,node_persistence,node_git toneAmber
class node_tools,node_permissions,node_context,node_memory,node_skills,node_mcp_runtime,node_lifecycle,node_reflection,node_tracing,node_mcp_servers toneMint
class node_providers,node_provider_models,node_mcp_cli toneRose
class node_user,node_model_service toneIndigo
```

## Components

### Ness CLI

- [CLI entry](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/tui/main.py): `src/ness_cli/tui/main.py`
- [Terminal UI](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/tui/app.py): `src/ness_cli/tui/app.py`
- [Headless runner](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/headless.py): `src/ness_cli/headless.py`
- [Session factory](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/factory.py): `src/ness_cli/factory.py`
- [Coding session](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/coding_session.py): `src/ness_cli/coding_session.py`
- [Git worktrees](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/worktree.py): `src/ness_cli/worktree.py`

### Agent Runtime

- [NessAgent](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/agent.py): `src/ness_agent/agent.py`
- [SDK session](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/session.py): `src/ness_agent/session.py`
- [Agent graph](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/graph/builder.py): `src/ness_agent/graph/builder.py`
- [Thread persistence](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/persistence.py): `src/ness_agent/persistence.py`

### Agent Capabilities

- [Built-in tools](https://github.com/sagnnik/ness-agent/tree/main/src/ness_agent/tools): `src/ness_agent/tools`
- [Tool permissions](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/permissions.py): `src/ness_agent/permissions.py`
- [Prompt context](https://github.com/sagnnik/ness-agent/tree/main/src/ness_agent/context): `src/ness_agent/context`
- [Memory](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/memory.py): `src/ness_agent/memory.py`
- [Skills](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/skills.py): `src/ness_agent/skills.py`
- [MCP runtime](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/mcp.py): `src/ness_agent/mcp.py`
- [Turn lifecycle](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/compaction.py): `src/ness_agent/compaction.py`
- [Reflection](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/reflection.py): `src/ness_agent/reflection.py`
- [Tracing](https://github.com/sagnnik/ness-agent/blob/main/src/ness_agent/tracing/tracer.py): `src/ness_agent/tracing/tracer.py`

### Providers & Integrations

- [Provider registry](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/provider/registry.py): `src/ness_cli/provider/registry.py`
- [Provider adapters](https://github.com/sagnnik/ness-agent/tree/main/src/ness_cli/provider): `src/ness_cli/provider`
- [Project MCP](https://github.com/sagnnik/ness-agent/blob/main/src/ness_cli/mcp_manager.py): `src/ness_cli/mcp_manager.py`

### Other components

- **Engineer**
- **Chat model**
- **MCP servers**
- **Git repository**

## Connections

- Engineer → CLI entry: starts session
- CLI entry → Terminal UI: opens UI
- CLI entry → Headless runner: runs prompt
- CLI entry → Session factory: builds session
- Terminal UI → Coding session: handles turns
- Headless runner → Coding session: runs turns
- Session factory → Coding session: creates
- Coding session → NessAgent: uses SDK
- NessAgent → SDK session: creates
- SDK session → Agent graph: runs
- Agent graph → Chat model: requests inference
- Agent graph → Built-in tools: dispatches tools
- Agent graph → Thread persistence: checkpoints state
- Provider registry → Provider adapters: resolves adapter
- Session factory → Provider registry: configures model
- SDK session → Prompt context: assembles prompt
- SDK session → Turn lifecycle: manages context
- SDK session → Reflection: finalizes turns
- Built-in tools → Tool permissions: checks access
- Built-in tools → Memory: accesses memory
- Built-in tools → Skills: uses skills
- CLI entry → Project MCP: configures MCP
- Project MCP → MCP runtime: coordinates
- MCP runtime → MCP servers: connects tools
- SDK session → Tracing: emits traces
- CLI entry → Git worktrees: prepares worktree
- Git worktrees → Git repository: creates worktree