SOKKAN Docs · Architecture

How SOKKAN works

Three diagrams, generated from the code and checked against it. Click a box to see what it does and what it talks to; press Live in the full view to trace the main path; Export gives you PNG, SVG or a WebM clip. Version française.

1.A session, end to end

You open a card or type a prompt. The API runs the memory search itself and writes the top notes into the session's first message, so the agent starts already knowing what previous sessions learned. The session runs on the Claude Agent SDK; every tool call that would change something goes through the HITL gate and comes back to you as a button. All of it lives in one container on your machine.

Boxes marked SRC link to the source file and line at a pinned commit.Open the interactive diagram ↗
Memory, guaranteedRecall is a server step, not a prompt the model may skip. Notes are plain markdown you own, indexed locally.
Human at the helmBash, Edit, Write and every MCP write wait for your click. Reads are auto-allowed. Telegram pings you when something waits.
Sovereign by defaultState, embeddings and transcripts stay in your Docker volume. The model is yours to pick: Anthropic key, Claude subscription, any compatible endpoint, or your own GPU.

Every box marked SRC links to the file and line in ninabot-ch/sokkan at the commit the diagram was generated from. If the diagram and the code disagree, the code wins and we regenerate.

2.From a card to an approved change

The loop you will run every day. The part that matters is the order: recall before any code, a plan grounded in notes and code, then a gate on every mutating step. Denied means the agent replans; it never bypasses. A card only reaches Done when a human moves it.

Signal-flow preset: the main path lights up every few seconds.Open the interactive diagram ↗

3.An agent run (Crew)

Crew agents run on their own: a cron, or a production alert. A run is still an ordinary session with the project memory, the agent's allowed tools, vault secrets by name and a per-run budget. It pauses the moment it wants to write, stops at 100 % of its budget, opens an incident if it fails, and the notes it writes stay quarantined until you promote them.

Every pause has an owner; every exit is explicit.Open the interactive diagram ↗

4.Going further