Managing Sessions

Session Modes

Katachi has two session modes, each designed for a different workflow:

Katachi Workspace

A freeform AI coding workspace. You provide a Git repository URL, and your Katachi agent securely clones it into ~/.katachi/repos on your machine. You chat directly with an AI assistant that has full access to this local workspace and your development tools. Think of it as a remote version of Claude Code or Gemini CLI — but accessible from any browser.

Key features:

• CodeMirror file viewer with syntax highlighting, file tree, tabs, and breadcrumbs
• Split diff view with live git status
• Markdown and image preview
• AI-first editing — all code changes via sandboxed, approval-gated tool calls
• Session context compaction (automatic context management for long conversations)
• Workspace memory injection (CLAUDE.md, GEMINI.md, .codex, agents, skills)

Katachi Flow

A Kanban-based task management system where AI agents handle cards through defined phases:

Phase	Description
Backlog	Cards waiting to be worked on
Planning	AI researches and plans the implementation
In Progress	AI writes code with tool use and orchestration
AI Review	Automated code review by a separate AI invocation
Human Review	You review the diff, approve or request changes
Done	Card complete, changes merged

Key features:

• Per-card git worktrees — Each card gets its own isolated Git worktree and branch, allowing up to 3 AI agents to work in parallel on different features without modifying your primary working directory.
• Card dependencies (DAG) — Define structured execution dependencies where cards automatically wait for their prerequisites to be completed and reviewed before starting.
• AI Review bouncing — If the AI’s code doesn’t pass peer verification, the review fails and the card is automatically bounced back to “In Progress” for a retry (up to 10 times by default).
• Vibes mode — Enforces a stricter zero-tolerance AI review policy and increases the bounce limit to 100 (effectively unlimited) for fully autonomous, hands-free execution.
• Context injection — Cards share learned context across the session
• Activity timeline — Track every action per card with timestamps
• Diff viewer — See exactly what the AI changed per card

Session Commander

When using Katachi Flow, the Session Commander acts as your AI project manager. It:

• Plans work by breaking tasks into cards
• Creates and prioritizes cards on the Kanban board
• Evaluates PR comments or issues to create actionable execution cards (if an MCP server or git provider CLI like gh or glab is installed and authenticated)
• Coordinates multi-card workflows by designing execution DAGs that group tasks into concurrent waves (maximizing parallel throughput while minimizing merge conflicts)
• Steps in to resolve Git merge conflicts when requested

You chat with the Session Commander the same way you’d chat in Workspace mode — it orchestrates the Kanban board on your behalf.

Creating a Session

1. Open katachi.live and log in
2. Click to create a new session
3. Select your workspace (git repository)
4. Choose an AI provider and model
5. Configure optional settings (approval mode, MCP servers, workspace features)
6. Start working

Approval Modes

Workspace sessions can optionally enable an approval system that gates AI tool operations. Configure this in your session settings.

Mode	Availability	Behavior
Yolo	Workspace (optional), Flow (mandatory)	Bypass all approvals — AI operates autonomously
Default	Workspace only	Auto-approve safe operations (reads, searches), prompt for writes and deletes
Strict	Workspace only	Prompt for every operation — maximum control

Flow sessions always run in Yolo mode because the AI needs to work autonomously through card phases (Planning → In Progress → AI Review) without manual intervention at every tool call.

Session Data

Session data is stored in two places:

• Backend — Session metadata, routing information
• Agent (local) — Chat history, file changes, git branches, workspace memory

Your code and conversation history never leave your machine — only metadata is stored in the cloud. Locally, your session data is stored in an encrypted SQLite database that uses a hardware-bound device fingerprint to prevent your data from being read if your files are copied to another machine.

Additionally, to ensure no session data or chat history is ever lost, the agent performs an automated database backup every time it starts, retaining a rolling history of your last 5 local database states.