OpenLobster

Agentic coding assistant — reads your codebase, edits files, runs commands, and integrates with your dev tools. Available in terminal, IDE and browser.

Status

Phase 0 — Foundation slice. This repository currently contains the Turborepo monorepo scaffold, shared workspace packages (types, config, validation, logger), and the PostgreSQL schema (packages/db) covering all entities described in CLAUDE.md. The API, Worker, Agent Harness, RAG pipeline, Tool Manager, MCP, Sandbox, and Model Gateway are not yet implemented — they are sequenced in subsequent slices, each one building on top of this foundation.

See CLAUDE.md at the repo root for the full architectural specification.

Repository layout

openlobster/
├── apps/                  # deployable services (api, worker, web, cli, tui) — coming in next slices
├── packages/
│   ├── db/                # PostgreSQL schema via Drizzle ORM + migrations
│   ├── types/             # cross-package domain types
│   ├── config/            # Zod-validated env config
│   ├── validation/        # shared Zod request/event schemas
│   └── logger/            # Pino structured logging
├── docker-compose.yml     # local Postgres + Redis + Chroma
├── turbo.json
├── tsconfig.base.json
└── package.json

Prerequisites

• Node.js >= 20
• npm (workspaces)
• Docker (only needed when you want the full Postgres + Redis + Chroma stack locally)

Quick start

# install
npm install

# start infrastructure (Postgres, Redis, Chroma)
docker compose up -d

# copy and fill env
cp .env.example .env

# apply database schema
npm run db:push

# typecheck the whole monorepo
npm run typecheck

Architectural rules (do not violate)

These are non-negotiable invariants from CLAUDE.md. Anything that violates them is a bug.

1. PostgreSQL is the source of truth. Redis and Chroma are transport/index — never store authoritative state in them.
2. The API never runs the agent. apps/api creates runs and returns 202 Accepted; apps/worker consumes from Redis and runs the Harness.
3. All tool execution passes through ToolManager. The LLM never calls the filesystem, terminal, git, or network directly.
4. All code execution happens inside the sandbox. No command generated by the model may execute on the host.
5. One active coding run per workspace. Workspace-level lock is enforced by the Worker.
6. Domain chain is fixed: User → Organization → Project → Workspace → Session → Task → Run → ToolCall / FileChange / Event.
7. Task vs. Run are distinct. A Task is "what the user wants"; a Run is one execution attempt of that Task. Retries create new Runs.

Slice roadmap

Slice	Scope	Status
0	Foundation: Turborepo + packages/{types,config,validation,logger,db} + docker-compose	in this slice
1	packages/auth (Argon2 + JOSE), packages/redis, REST API skeleton	next
2	apps/api: auth, projects, workspaces, sessions, messages endpoints	next
3	packages/events, SSE gateway, /v1/runs/:id/events	next
4	apps/worker: queue consumer + run lease + Harness shell	next
5	packages/models (Model Gateway) + provider adapters	next
6	packages/context + packages/rag (Chroma + embeddings + indexer)	next
7	packages/tools + packages/mcp + filesystem / git / terminal tools	next
8	packages/sandbox (Docker) + ToolManager wired	next
9	Agent Loop inside Harness: reason → tool → observe → repeat	next
10	Web (Next.js) and TUI clients consuming the API	next

Each slice lands as a coherent, type-checked, runnable increment.

License

TBD.