← The Karsa Manual

Using Karsa

Karsa runs as a local daemon (karsa-server) with a web UI at localhost:3100. Everything you do lives in projects, and every project is just plain files on disk — versioned in git, yours to keep, readable without Karsa at all. This page is the lay of the land.

The daemon and $KARSA_HOME

One daemon serves the whole machine. Its state lives under $KARSA_HOME (by default ~/.karsa): the project registry (projects.yaml), machine config (KARSA.md), and this manual (doc/). The daemon is a pure function of its --home flag — there is no hidden environment fallback, so a misconfigured launch fails loudly instead of pointing at the wrong data.

The Karsa System project is a special project whose project_home is $KARSA_HOME. Unlike a normal project it runs uncaged — it can manage, fix, create, and import your other projects, and install the tools Karsa depends on. Its home page is what you see at the root of the UI.

Projects

A project is a unit of work with its own data, its own worker, and its own cage. You create one by picking a template, or by describing the system you want and letting Karsa scaffold it — collections, workers, schedules — for your use case.

On disk a project lives under {project_home}/karsa/proj_*/:

• artifact/ — your collections (typed data: specs, notes, tables, files).
• sqldb/ — application data (SQL tables backing your app).
• index.md — the project's home page; its body is yours to edit.

Everything is versioned in git per project. If you lose the registry, a project can be re-imported from its folder alone, because the folder is self-describing.

Collections

Collections are your typed data. Pick the shape that fits:

• Tabular data you'll filter, sort, and join → a Karsa SQL DB table, exposed as a collection.
• Files (CSV / PDF / images / datasets) → the Files collection.
• Notes, specs, memos → a markdown collection (one .md per resource, frontmatter + body).

Each markdown resource has YAML frontmatter (its typed fields) and a markdown body. The UI renders both with the shared frontmatter + markdown views; ids cross-link automatically.

Chat — plan, then work

Open Chat in a project and describe what you want. Two agents split the job:

• The planner talks with you. For a quick question it just answers; for anything that changes things it records a short rationale, and for multi-step work it opens a workflow (its shared scratchpad) and breaks the goal into tasks. It never writes code itself.
• The worker picks up each task the moment it's ready, runs it to completion (reading/writing files, running commands, using the SDK — all inside the project cage), and records the outcome. Several can run at once.

You watch it happen in the chat: as the worker moves a task (claimed → done / failed), a one-line status appears in the conversation, with ids that link to the task and its exec log.

Both agents run on an agent CLI you install — Claude Code or Codex (each needs a paid subscription). Seed both if you like; Karsa uses whichever is installed (Claude first). If neither is present, the planner replies in chat telling you how to install one — or run karsa doctor.

Schedule, Browse, Search

• Schedule — a one-off ("run in undefined minutes") or a recurring job, so work happens without you sitting there.
• Browse — every file on disk under the project, with text preview.
• Search — full-text across everything the project holds.

Where to go next

When a task produces data, read Data and storage — it's the rule for where each shape of output lives (assets, sqldb + collections, docdb docs) and the HTTP API conventions for putting it there. When the task shifts from "organize data" to "build an app," read Building a Karsa app — the app belongs inside the project, on the Karsa SDK, not in a scratch directory wired to an outside service. If you find yourself reaching outside, read Anti-patterns first.