Projects & workspaces

How KrowForge maps your code to its world.

Workspace = project

Each project lives in its own workspace. Workspaces are isolated: separate file tree, terminal sessions, agent runs, secrets, settings.

Server-side, a workspace is a directory: workspaces/<slug>/. The slug is derived from the project's path or set explicitly when you load a folder.

Loading a project

POST /api/project/load
{ "path": "/path/to/your/project" }

The path is validated for safety (must be readable, must exist, must not be a system directory). If valid:

  1. The workspace becomes "active" in your session.
  2. repo_scanner runs to detect framework, languages, entry points.
  3. symbol_indexer builds the symbol index.
  4. sec_scanner populates findings.

In the UI: click Open folder on the welcome screen, paste a path, hit Enter.

Switching projects

Several routes:

  • Recent projects — GET /api/project/recent returns your last-N opened workspaces. Surfaced in the top breadcrumb.
  • Command palette — ⌘K → "Switch project".
  • Welcome screen — when no project is active.

What lives in a workspace

File / dirPurpose
<your code>The actual project files.
.krowforge/settings.jsonPer-workspace settings (autonomy, budget, theme, etc.).
.krowforge/keybindings.jsonCustom keybindings overrides.
.krowforge/secrets.encEncrypted secret store.
.krowforge/snapshots/Snapshot ring buffer.
.krowforge/receipts/Receipt audit chain.
.krowforge/vault/Vault notes (alpha).

The .krowforge/ directory is created lazily — only when needed.

Recent projects

GET /api/project/recent returns up to 20 entries with last-opened timestamp and project name. Used by the breadcrumb dropdown and command palette.

Project memory

Some agent context is preserved across runs in .krowforge/memory.json:

  • "What did I learn about this codebase?" notes.
  • Per-file conventions the agent picked up.
  • Tagging info.

The memory is read at the start of every run. You can clear it from Settings → Project → Clear memory.