Fishbowl

Why Fishbowl

Engineering teams often solve the same problem twice: the important context is trapped in terminal scrollback, issue threads, and someone’s memory. Fishbowl keeps a project-local, reviewable record without pretending that every note is a proven fact.

Related MCP server: UseCortex MCP Server

What You Get

• fishbowl CLI for registering projects, querying context, recording cases, and checking integrity.

• Persistent local daemon that owns one authenticated SQLite connection and local cache.

• stdio MCP server for compatible coding agents.

• Trace Bench, a read-only local browser for inspecting project activity.

• Worktree-aware project aliases so parallel branches still share the right engineering context.

Quick Start

macOS / Linux

git clone https://github.com/nimocat/fishbowl.git
cd fishbowl
npm install
npm run build
npm link

fishbowl daemon install
fishbowl daemon doctor

Windows (PowerShell)

Install Node.js 22 or newer, Git, Rust stable with the MSVC toolchain, and the Visual Studio Build Tools C++ workload, then run:

git clone https://github.com/nimocat/fishbowl.git
Set-Location fishbowl
npm install
npm run build
npm link

fishbowl daemon install
fishbowl daemon doctor

The daemon runs only for the current user. No administrator account is required. Its first fixed-endpoint launch stores one high loopback port in the private Fishbowl data directory and reuses that port across installs and updates. An update already running this fixed-endpoint CLI snapshots the current valid descriptor port before shutdown, so MCP clients do not lose the daemon merely because its process restarted. daemon install waits for authenticated readiness and reports a port conflict instead of silently moving the endpoint.

CLI help and diagnostics

Running fishbowl with no arguments now prints the full command overview and does not start the daemon. Help is available in equivalent forms:

fishbowl help
fishbowl help project register
fishbowl project register --help
fishbowl --version

Invalid commands and missing options return JSON with the original message plus command-specific usage, an actionable hint, and the exact help command to run. Use fishbowl daemon doctor for connectivity diagnostics and fishbowl integrity for a read-only database check. Data-oriented CLI entries remain legacy/manual-recovery compatibility only; coding Agents call Fishbowl MCP tools directly.

Register a Project

The following data commands are retained for explicit human recovery and compatibility. Configure coding Agents to use the equivalent Fishbowl MCP tools.

cd /absolute/path/to/your-project
fishbowl project register \
  --root "$PWD" \
  --name "My Project" \
  --description "Local engineering knowledge"

Copy the returned project ID and use it in the normal loop:

fishbowl query --project "<project-id>" "export failure"
fishbowl checkpoint \
  --project "<project-id>" \
  --task "Fix export failure" \
  --outcome succeeded \
  --summary "Moved composition work off the main actor and passed focused verification."

Give Fishbowl to Codex or Another Agent

Configure the user-level stdio MCP server once, then copy the MCP Agent Session Prompt into a coding agent. It tells the agent to choose a proportional LIGHT, STANDARD, or FULL workflow and to:

1. Call Fishbowl MCP tools directly and resolve the project explicitly.

2. Use compact, Case-diverse history results and expand only selected Cases.

3. Reserve preflight for work whose risk justifies it; use checkpoints only for real interruption or handoff.

4. Report an unavailable MCP server instead of falling back to the CLI.

The MCP client starts this persistent stdio bridge from its server configuration:

node /absolute/path/to/fishbowl/dist/cli/main.js mcp --stdio

See the ready-to-copy MCP client configurations. Codex must not launch this command itself or use CLI query/write commands. The configured MCP host owns the process and its stdout protocol frames.

The Engineering Loop

LIGHT:    Resolve -> Query when useful -> Answer
STANDARD: Resolve -> Brief preflight/query -> Problem -> Implement -> Commit/verify -> Finalize once
FULL:     Resolve -> Preflight/query -> Problem/valuable failures -> Commit/verify -> Finalize once

checkpoint_work is an interruption primitive, not a mandatory pre-finalize step. Use it only for context compaction, a cross-day pause, or a handoff. When finalization follows a necessary checkpoint, pass its caseId and checkpointOperationId; Fishbowl explicitly reuses that checkpoint knowledge. Human Verification is recorded only after a person confirms the real target behavior.

Disk observation has been retired. Current Fishbowl releases do not scan project disks or expose artifact-growth/cleanup-candidate tools; historical schema tables remain inert only for non-destructive upgrades.

Fishbowl keeps records distinct so the graph remains useful under review:

Local-First by Design

CLI / MCP client
       |
       v
Fishbowl daemon (current user, authenticated)
       |
       +-- SQLite knowledge store
       +-- bounded raw command-log references
       +-- Trace Bench on 127.0.0.1 only

• No account, hosted service, cloud sync, or telemetry is required.

• Durable graph text is recursively secret-redacted and bounded.

• Raw command logs remain local, retention-bounded, and excluded from graph exports.

• Existing repositories are never modified merely by being registered.

Read SECURITY.md before sharing any data directory or raw log collection.

Upgrade from Engineering Knowledge Graph

The first Fishbowl launch migrates the legacy local database, WAL files, token, and raw logs into the Fishbowl data directory. Existing graph exports remain import-compatible; newly created exports use the fishbowl format marker.

Run once after upgrading:

fishbowl daemon install

Updating on Windows (PowerShell)

After installing this release, routine updates are one human-run PowerShell command:

fishbowl update

The command accepts only a clean checkout of the official Fishbowl origin/main. It fast-forwards, runs npm ci, builds production artifacts, refreshes npm link, reinstalls and starts the current-user daemon, and completes a health check. It never uses reset --hard, overwrites local changes, or switches branches. Knowledge under %LOCALAPPDATA%\Fishbowl is preserved. A failed deployment restores the prior CLI and daemon when possible; rerunning the command repairs an incomplete deployment instead of skipping merely because the source is current.

If an older release reports Unknown command: update, bootstrap the command once in the Fishbowl repository you originally cloned. If git status --short shows your own changes, commit or stash them first:

The source build requires Node.js 22 or newer, Git, Rust stable with the MSVC toolchain, and the Visual Studio Build Tools C++ workload.

Set-Location C:\path\to\fishbowl
git status --short
git pull --ff-only origin main
npm ci
npm run build
npm link

fishbowl daemon install

After every successful update, fully quit and restart the MCP client (for example Codex or Claude Desktop) so it loads new MCP tools and schemas. The stable daemon port lets an existing bridge reconnect after an ordinary daemon restart, but cannot hot-reload adapter code. Agents do not need—and must not try—to locate or run fishbowl update or any other Fishbowl CLI themselves.

If the MCP client already points to the absolute dist\cli\main.js path in the same clone, its configuration does not change. If the clone moved, update it once using Windows MCP paths.

Development

npm install
npm run typecheck
npm test
cargo test --workspace
npm run build

See CONTRIBUTING.md for the contribution workflow and docs/ for architecture, protocol, migration, and recovery notes.