Your first session

Open the workspace

Open SenkaniApp from /Applications (or build it locally and run .build/release/SenkaniApp). A Welcome surface appears with a Choose project folder step at the top — Senkani won't start an agent until you tell it which repo to run in.

Pick the project folder

Click Choose project folder and select the directory of the repo you want the agent to work in. The Welcome surface collapses to a Project: <name> row, and the four task starter cards below flip from Choose a project folder first to project-aware verbs: Ask Claude in <name>, Use Ollama in <name>, Open a tracked shell in <name>, and Inspect this project in <name>.

Prefer a tracked shell in your home folder instead? Click Open a tracked shell in home folder — that's the deliberate escape hatch and the only path that lands a session at ~. Need a pane the four starters don't cover? Use the Show all panes link below the starter cards to open the full 19-pane gallery.

Below the starter cards, a modest Next: <step> banner names the early-use milestone you haven't hit yet — first project picked, first agent launched, first tracked event, first non-zero savings, first budget set, first workstream created, first staged proposal reviewed. When the next milestone is first workstream created, the banner becomes tappable and opens New Workstream inline; the active project's WORKSTREAMS sidebar is also visible from first launch (the previous "two-or-more workstreams" gate is gone) so the same affordance is reachable passively. The banner disappears once all seven fire so a returning user isn't nagged after onboarding ends. Senkani records the timestamps locally at ~/.senkani/onboarding/milestones.json (mode 0600, no upload path); set SENKANI_ONBOARDING_MILESTONES=off to opt out entirely. Inspect the live env-var status + on-disk JSON with senkani onboarding milestones — a read-only subcommand that prints the gate state, the resolved path, the file's pretty-printed JSON (or (file does not exist yet)), and a derived summary.allComplete line. Reads bypass the env gate so =off still surfaces on-disk truth (the gate is opt-out-of-recording, not opt-out-of-observability); cat ~/.senkani/onboarding/milestones.json is the script-friendly raw fallback.

Start the agent

Click Ask Claude in <project>. Senkani opens a launcher sheet for picking the Claude command, then assembles the first-value layout: a Terminal pane in the project root running the chosen launcher (the MCP handshake happens automatically) and an Agent Timeline pane next to it so optimization events appear as the agent works — no need to open it manually. The Terminal pane header reads the actual working directory — ~/Desktop/projects/<project> — not a bare ~. Re-clicking Ask Claude later only adds another Terminal pane; the timeline isn't duplicated.

Above the terminal output, the active terminal pane shows a Senkani Active proof strip with five labelled chips. Each chip flips to OK when its component is wired up; if any are missing, a banner row beneath the chips surfaces the next runnable action — no waiting for the first intercepted command to learn whether Senkani is in the loop.

• PROJECT — a project root is selected for the pane.
• MCP — Senkani's MCP server entry exists in ~/.claude/settings.json.
• HOOKS — PreToolUse + PostToolUse hooks are registered in <project>/.claude/settings.json (run senkani init if missing).
• TRACK — the in-process session watcher is running.
• EVENTS — at least one tool-call event has been recorded for this project (relative-age detail keeps updating).

Open extra inspection panes

The Agent Timeline already opened next to the Terminal as part of the first-value layout. To see compression numbers across every pane, ⌘K → "Analytics". To watch a specific pane's filter pipeline, ⌘K → "Savings Test". The optimization layer is already running; these surfaces let you watch it from a different angle.

Ask for something real

Ask the agent to do something that involves reading your project:

> Find the function that handles order pagination.

Watch the Agent Timeline pane fill with tool calls (senkani_search → senkani_fetch → possibly senkani_read). Each line shows the tool, target, and compression ratio.

Read the Analytics pane

• Tokens saved — bytes that would have been sent to the LLM but weren't.
• Cost saved — tokens × model rate (from the pane's model preset).
• Compliance rate — fraction of tool calls that went through Senkani vs the agent's built-ins. High is good.
• Per-feature breakdown — F / C / S / I / T contributions.