Cortex

An agentic platform for understanding and evolving codebases. Cortex indexes your repositories, builds an architecture model, designs solutions, and implements them as PRs.

Architecture

Monorepo managed with pnpm workspaces.

Package	Description
packages/api	Hono API server (PostgreSQL via Drizzle, agent execution, git integration)
packages/web	React + Vite + Tailwind frontend
packages/sandbox	Sandbox runner for executing agent jobs
packages/agent-core	Generic agent framework — Agent, AgentLoop, ConversationStore, DynamoDB/Redis state, hooks, compaction, SSE streaming
packages/agent	Cortex-specific agent layer — built-in tools (Read/Glob/Grep/Edit/Write/Bash/Agent/AskUserQuestion/TodoWrite/Task*), default prompts, Anthropic client factory (auto-detects Bedrock vs direct API)

The agent stack is built around @cortex/agent-core (the framework) and @cortex/agent (the Cortex tools and helpers on top). The API consumes both via the workspace.

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker (for the local Postgres)
• AWS credentials (for Bedrock) or an Anthropic API key

Setup

cp .env.example .env       # fill in credentials
pnpm install
docker compose up -d postgres
pnpm -F @cortex/api db:push

Environment

Set one of:

# Direct Anthropic API
ANTHROPIC_API_KEY=sk-ant-...

# OR AWS Bedrock (uses standard AWS credential chain)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

The getAnthropicClient() factory in @cortex/agent auto-detects which provider to use: if ANTHROPIC_API_KEY is set, it uses the direct API; otherwise it falls back to Bedrock.

Optional:

CORTEX_MODEL=us.anthropic.claude-sonnet-4-6
CORTEX_MODEL_SUBAGENT=us.anthropic.claude-sonnet-4-6
GITHUB_TOKEN=...           # for git operations

See .env.example for the full list.

Development

make dev                   # starts Postgres + API + Web
# or:
pnpm dev                   # API + Web (without docker)
pnpm dev:api               # API only
pnpm dev:web               # Web only

The API runs on http://localhost:4000, the web app on http://localhost:5173 (Vite proxies /api → :4000).

In dev mode, tsx runs the TypeScript source directly — no build step needed for the agent packages.

Build

pnpm run build

This builds packages in dependency order: agent-core → agent → api → web.

For production, the API runs the compiled JS from packages/api/dist/. The agent packages need their dist/ folders present (built via tsc), and package.json exports points there.

Database

pnpm -F @cortex/api db:push       # apply schema changes (no migrations)
pnpm -F @cortex/api db:studio     # browse the DB in a UI

Schema lives at packages/api/src/lib/db/schema.ts.

Type-check

pnpm type-check                   # all packages
pnpm -F @cortex/api type-check    # one package

Docker

docker build -t cortex .
docker run -p 4000:4000 --env-file .env cortex

The Dockerfile builds all packages, deploys the API + sandbox via pnpm deploy, and runs as a non-root user.

Agent tools

The Cortex agent ships with these built-in tools (from @cortex/agent):

Tool	Purpose
Read	Read a file with line numbers
Glob	Find files by glob pattern (sorted by mtime)
Grep	Search file contents via ripgrep
Edit	Exact-match string replacement in a file
Write	Write a file (creates parent dirs)
Bash	Execute a shell command
Agent	Spawn a sub-agent with its own tools and prompt
AskUserQuestion	Pause the loop to ask the user multiple-choice questions
TodoWrite	Track an in-memory todo list
TaskCreate/Get/List/Update/Stop/Output	Full task management (V2)

Custom tools can be defined with defineTool() or the backwards-compat tool() helper. See packages/agent/src/tools/ for examples.

Multi-tenancy

All database queries must be scoped by workspace_id or user_id. There's no row-level security — scoping is enforced in application code.