# ilhanakd-max/local_ajan architecture

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

- Interactive diagram: https://gitdiagram.com/ilhanakd-max/local_ajan
- Repository: https://github.com/ilhanakd-max/local_ajan

## Overview

LocAi is a terminal coding-agent runtime: a user submits a task through the CLI, the agent prompts a selected model, parses its response for tool requests, executes approved project operations, and feeds results back for further steps or a final answer. The graph also covers documented sessions, model-specific behavior, Brain/Worker orchestration, and provider integrations. Evidence is strongest for the sampled CLI, parser, tool, session, safety, and client code; some links to unsampled runtime modules follow the README’s stated workflow, so uncertain call wiring is omitted.

Main entry points: [`src/lokal_ajan/agent/loop.py`](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/loop.py) (Agent loop), [`src/lokal_ajan/cli.py`](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/cli.py) (CLI commands), [`src/lokal_ajan/tools/registry.py`](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/registry.py) (Tool registry), [`src/lokal_ajan/tools/fs_tools.py`](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/fs_tools.py) (File and search tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_console["Terminal UI<br/>[console.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Agent loop<br/>[loop.py]"]
  node_prompt["Prompt building<br/>[prompt.py]"]
  node_history["Conversation history<br/>[history.py]"]
  node_context["Context management<br/>[context.py]"]
  node_parser["Tool-call parser<br/>[parser.py]"]
  node_thinking["Thinking control<br/>[thinking.py]"]
  node_orchestrator["Brain / Worker"]
end

subgraph group_workspace["Project tools and safety"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_filetools["File and search tools<br/>[fs_tools.py]"]
  node_shell["Shell execution<br/>[shell_tool.py]"]
  node_git["Git inspection<br/>[git_tools.py]"]
  node_sandbox["Workspace sandbox<br/>[sandbox.py]"]
  node_confirm["Action confirmation<br/>[confirm.py]"]
end

subgraph group_models["Models and providers"]
  node_profiles["Model profiles<br/>[model_profiles.py]"]
  node_ollama["Ollama client<br/>[ollama_client.py]"]
  node_openrouter["OpenRouter client"]
  node_groq["Groq client<br/>[groq_client.py]"]
  node_ninerouter["NineRouter client"]
  node_nvidia["NVIDIA client<br/>[nvidia_client.py]"]
end

subgraph group_state["Sessions and configuration"]
  node_session["Session persistence<br/>[session.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Developer"))
node_workspace_files["Project workspace"]
node_ollama_service(("Ollama service"))
node_cloud_models(("Hosted model APIs"))

node_user -->|"submits task"| node_cli
node_cli -->|"renders interaction"| node_console
node_cli -->|"starts agent"| node_loop
node_cli -->|"loads settings"| node_config
node_cli -->|"manages sessions"| node_session
node_loop -->|"builds prompt"| node_prompt
node_loop -->|"updates history"| node_history
node_loop -->|"bounds context"| node_context
node_loop -->|"selects profile"| node_profiles
node_loop -->|"requests completion"| node_ollama
node_loop -.->|"requests completion"| node_openrouter
node_loop -.->|"requests completion"| node_groq
node_loop -.->|"requests completion"| node_ninerouter
node_loop -.->|"requests completion"| node_nvidia
node_ollama -->|"streams requests"| node_ollama_service
node_openrouter -.->|"streams requests"| node_cloud_models
node_groq -.->|"streams requests"| node_cloud_models
node_ninerouter -.->|"streams requests"| node_cloud_models
node_nvidia -.->|"streams requests"| node_cloud_models
node_loop -->|"parses response"| node_parser
node_parser -->|"checks tool names"| node_registry
node_loop -->|"dispatches tool"| node_registry
node_registry -->|"dispatches tool"| node_filetools
node_registry -->|"dispatches tool"| node_shell
node_registry -->|"dispatches tool"| node_git
node_filetools -->|"reads and writes"| node_workspace_files
node_shell -->|"operates in"| node_workspace_files
node_git -->|"inspects changes"| node_workspace_files
node_shell -->|"requests approval"| node_confirm
node_filetools -->|"requests approval"| node_confirm
node_loop -->|"constrains operations"| node_sandbox
node_loop -.->|"delegates tasks"| node_orchestrator
node_loop -->|"saves and loads"| node_session

click node_cli "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/cli.py"
click node_console "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/ui/console.py"
click node_loop "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/loop.py"
click node_prompt "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/prompt.py"
click node_history "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/history.py"
click node_context "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/context.py"
click node_parser "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/parser.py"
click node_thinking "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/thinking.py"
click node_orchestrator "https://github.com/ilhanakd-max/local_ajan/tree/main/src/lokal_ajan/agent"
click node_registry "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/registry.py"
click node_filetools "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/fs_tools.py"
click node_shell "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/shell_tool.py"
click node_git "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/git_tools.py"
click node_sandbox "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/safety/sandbox.py"
click node_confirm "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/safety/confirm.py"
click node_profiles "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/model_profiles.py"
click node_ollama "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/ollama_client.py"
click node_openrouter "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/openrouter_client.py"
click node_groq "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/groq_client.py"
click node_ninerouter "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/ninerouter_client.py"
click node_nvidia "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/nvidia_client.py"
click node_session "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/session.py"
click node_config "https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/config.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_cli,node_console toneBlue
class node_loop,node_prompt,node_history,node_context,node_parser,node_thinking,node_orchestrator toneAmber
class node_registry,node_filetools,node_shell,node_git,node_sandbox,node_confirm,node_cloud_models toneMint
class node_profiles,node_ollama,node_openrouter,node_groq,node_ninerouter,node_nvidia toneRose
class node_session,node_config,node_user,node_workspace_files,node_ollama_service toneIndigo
```

## Components

### CLI and interaction

- [CLI commands](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/cli.py): `src/lokal_ajan/cli.py`
- [Terminal UI](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/ui/console.py): `src/lokal_ajan/ui/console.py`

### Agent runtime

- [Agent loop](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/loop.py): `src/lokal_ajan/agent/loop.py`
- [Prompt building](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/prompt.py): `src/lokal_ajan/agent/prompt.py`
- [Conversation history](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/history.py): `src/lokal_ajan/agent/history.py`
- [Context management](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/context.py): `src/lokal_ajan/agent/context.py`
- [Tool-call parser](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/parser.py): `src/lokal_ajan/agent/parser.py`
- [Thinking control](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/thinking.py): `src/lokal_ajan/agent/thinking.py`
- [Brain / Worker](https://github.com/ilhanakd-max/local_ajan/tree/main/src/lokal_ajan/agent): `src/lokal_ajan/agent`

### Project tools and safety

- [Tool registry](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/registry.py): `src/lokal_ajan/tools/registry.py`
- [File and search tools](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/fs_tools.py): `src/lokal_ajan/tools/fs_tools.py`
- [Shell execution](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/shell_tool.py): `src/lokal_ajan/tools/shell_tool.py`
- [Git inspection](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/tools/git_tools.py): `src/lokal_ajan/tools/git_tools.py`
- [Workspace sandbox](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/safety/sandbox.py): `src/lokal_ajan/safety/sandbox.py`
- [Action confirmation](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/safety/confirm.py): `src/lokal_ajan/safety/confirm.py`

### Models and providers

- [Model profiles](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/model_profiles.py): `src/lokal_ajan/llm/model_profiles.py`
- [Ollama client](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/ollama_client.py): `src/lokal_ajan/llm/ollama_client.py`
- [OpenRouter client](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/openrouter_client.py): `src/lokal_ajan/llm/openrouter_client.py`
- [Groq client](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/groq_client.py): `src/lokal_ajan/llm/groq_client.py`
- [NineRouter client](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/ninerouter_client.py): `src/lokal_ajan/llm/ninerouter_client.py`
- [NVIDIA client](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/llm/nvidia_client.py): `src/lokal_ajan/llm/nvidia_client.py`

### Sessions and configuration

- [Session persistence](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/agent/session.py): `src/lokal_ajan/agent/session.py`
- [Configuration](https://github.com/ilhanakd-max/local_ajan/blob/main/src/lokal_ajan/config.py): `src/lokal_ajan/config.py`

### Other components

- **Developer**
- **Project workspace**
- **Ollama service**
- **Hosted model APIs**

## Connections

- Developer → CLI commands: submits task
- CLI commands → Terminal UI: renders interaction
- CLI commands → Agent loop: starts agent
- CLI commands → Configuration: loads settings
- CLI commands → Session persistence: manages sessions
- Agent loop → Prompt building: builds prompt
- Agent loop → Conversation history: updates history
- Agent loop → Context management: bounds context
- Agent loop → Model profiles: selects profile
- Agent loop → Ollama client: requests completion
- Agent loop → OpenRouter client: requests completion
- Agent loop → Groq client: requests completion
- Agent loop → NineRouter client: requests completion
- Agent loop → NVIDIA client: requests completion
- Ollama client → Ollama service: streams requests
- OpenRouter client → Hosted model APIs: streams requests
- Groq client → Hosted model APIs: streams requests
- NineRouter client → Hosted model APIs: streams requests
- NVIDIA client → Hosted model APIs: streams requests
- Agent loop → Tool-call parser: parses response
- Tool-call parser → Tool registry: checks tool names
- Agent loop → Tool registry: dispatches tool
- Tool registry → File and search tools: dispatches tool
- Tool registry → Shell execution: dispatches tool
- Tool registry → Git inspection: dispatches tool
- File and search tools → Project workspace: reads and writes
- Shell execution → Project workspace: operates in
- Git inspection → Project workspace: inspects changes
- Shell execution → Action confirmation: requests approval
- File and search tools → Action confirmation: requests approval
- Agent loop → Workspace sandbox: constrains operations
- Agent loop → Brain / Worker: delegates tasks
- Agent loop → Session persistence: saves and loads