How sagnnik/ness-agent works
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: main.py CLI entry · session.py SDK session · builder.py Agent graph · tools Built-in tools
Components 26
Ness CLI
- CLI entry
src/ness_cli/tui/main.py - Terminal UI
src/ness_cli/tui/app.py - Headless runner
src/ness_cli/headless.py - Session factory
src/ness_cli/factory.py - Coding session
src/ness_cli/coding_session.py - Git worktrees
src/ness_cli/worktree.py
Agent Runtime
- NessAgent
src/ness_agent/agent.py - SDK session
src/ness_agent/session.py - Agent graph
src/ness_agent/graph/builder.py - Thread persistence
src/ness_agent/persistence.py
Agent Capabilities
- Built-in tools
src/ness_agent/tools - Tool permissions
src/ness_agent/permissions.py - Prompt context
src/ness_agent/context - Memory
src/ness_agent/memory.py - Skills
src/ness_agent/skills.py - MCP runtime
src/ness_agent/mcp.py - Turn lifecycle
src/ness_agent/compaction.py - Reflection
src/ness_agent/reflection.py - Tracing
src/ness_agent/tracing/tracer.py
Providers & Integrations
- Provider registry
src/ness_cli/provider/registry.py - Provider adapters
src/ness_cli/provider - Project MCP
src/ness_cli/mcp_manager.py
Other components
- Engineer
- Chat model
- MCP servers
- Git repository
Connections 27
- 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