Two minds. One workspace. Force multipliers for each other.
You keep working when the agent is offline. The agent keeps working when you step away. Based is the convergence layer that makes two parallel workstreams compound instead of collide — same terminal, same filesystem, same memory, same source of truth.
Not a wireframe, not a raw screenshot. One frame compressing what's actually true at any given moment in Based: an agent is mid-edit on something you set down earlier, you're walking back to a workspace that already has drafts waiting, and the memory has already updated for both of you.
https://based.local/#/terminal?base=based-web
healthy
realm: thcllc
claude -> codex -> gemini
terminal / based-web-codex
focus: base
broadcast off
tmux attached
shared terminal80x24
codex running while you were away: + read context, indexed shared filesystem + drafted Browser Mockup section + wrote MEMORY.md note for next session
$based_agent_contact to=claude intent=request codex asks claude: review tone before deploy ok mailbox write seq=118 wake=ping_attempted
you walk back in, terminal still attached $git diff repos/based-web/index.html
draft is staged, decision is yours
file diff
repos/based-web/index.html - static explanation only + browser mockup scene + agent status rail + terminal playback + mailbox and memory feed
visual story
human asks
agent reads context
files change
status returns
messagesboth workstreams visible
youDrop: the hero is too tool-shaped. It should land force multiplier.
codexDrafted three rewrites, staged the strongest. Diff in repos/based-web.
claudeReviewing tone. Flagged one phrase that contradicts the docs.
memorywhat both of you put down
.memory/MEMORY.md
Force-multiplier framing: copy should land that human and agent are both autonomous workers. Avoid "AI does the work" stance. Avoid magic-box framing. Walk-on-train, agent-edits-while-you-sleep — both are real workstreams.
01You think on it overnight
You jot a note, drop a question in mailbox, leave a clue in memory. Workstream one is running — it's just running in your head.
02The agent picks it up
It reads what you left, queries the same domains you would, drafts a path forward. Workstream two is running — it's just running while you sleep.
03You walk back in
Drafts are waiting. The diff is staged. The agent's reasoning is in memory, and the things only you can decide are still yours to decide.
04The workspace remembers
What both of you put down compounds. Next session — yours or theirs — starts from where the team is now, not where one of you left off.
Philosophy
You don't stop thinking when the agent is working. The agent doesn't stop when you step away. Based is the workspace where two parallel workstreams hand each other batons instead of waiting their turn.
Most tools treat the asymmetry between human and AI work as a problem to translate around. Based treats it as the whole point. You're processing the problem on a walk; the agent is rewriting a module; both are real work, neither is waiting on the other.
The workspace is what makes that compound instead of collide. Filesystem is where each of you drops work the other will find. Mailbox is the baton handoff — durable when nobody's around, urgent when somebody needs to act. Memory is where the team's understanding accumulates across sessions, agents, and provider switches. The 13 structured domains mean both of you query the same source of truth.
This isn't AI-as-assistant or human-as-supervisor. It's two autonomous workers extending each other's reach — you bring intuition, taste, and context the agent can't infer; the agent brings parallelism, recall, and tireless follow-through you can't sustain. Each one's strength covers the other's gap.
You're not managing an AI. You're working with one. Same context. Same tools. Same room. The workspace remembers what both of you put down.
Co-Work
Two workstreams. One source of truth.
Each surface in Based is a place where two parallel workers — one human, one agent — deposit and pick up state. Not a tool the human drives; a workspace they share.
Humans + Agents
Either of you can drive
Real PTY sessions in tmux. Whoever's hands are free types — the human grabs the keyboard, the agent sends keystrokes, broadcast mode syncs across panes. No simulator, no sandbox. The room is real, and you both walk into it.
Humans + Agents
Drop work where the other will find it
Convention-driven project discovery. Drop a manifest in any directory and it exists. The agent's edits show up in your tree; your notes show up in the agent's context. Same files, same configs, same paths — which means handoffs cost zero translation.
Agents
The agent doesn't need a sherpa
One self-describing manifest. Every domain, field, filter, and query pattern discoverable at runtime — plus 57 native MCP tools. You're not the agent's onboarding buddy; the workspace tells it what's here. Frees you to do the work only you can do.
Human self-serve
Everything the agent sees, you see
21-mode dashboard — file explorer, session browser, infrastructure map, terminal grid, notes, memory, logs, usage analytics, kanban. Keyboard-driven. The agent's transcripts, tool calls, and decisions are all surfaced. Co-work needs symmetric visibility.
Humans
Stay in the zone the agent can't reach
Queue the tracks that put you in flow. Not a streaming service — a focus tool. Three songs on repeat for six hours. You know the ones. Built in because deep work isn't just code — it's state of mind, and the agent can't carry that part for you.
Humans + Agents
Coordination — intent, watchdog, escalation
Contact — based_agent_contact with an intent (request, status, fyi, completion). Active intents wake the recipient; passive ones don't. Typos resolve to suggestions. Missing target sessions auto-start. Watchdog — activations missed by a busy TUI get auto-resent. Every send returns a structured deliveryState. /api/messages/coord-health exposes the layer to the web. Followup — when a peer goes quiet, based_agent_followup picks an escalation: inspect, reping, send_followup, proceed_alone, ask_user, mark_blocked. Coordination is observable, not hopeful. Underneath — file-backed inbox, base box file drops, and tmux base beam send-keys still exist as primitives. based_agent_contact picks the right one for the intent.
Terminal-First
The terminal is the workspace
Not a terminal emulator bolted onto a dashboard. The terminal is where work happens — Based orchestrates around it.
based — streaming-infra
❯base startstreaming-infra→ resuming tmux session→ provider: claude (opus)→ memory loaded: 3 topics→ context: 47 prior sessions ❯base beam"run the migration"→ sent to: streaming-infra ❯base status streaming-infra claude 12m active dashboard codex 4m idle fleet-manager gemini 28m active
Start a session. Pick a provider. Work.
base start launches a tmux session with your chosen AI provider — Claude, Codex, Gemini, or a local Ollama model. Sessions persist. Context carries over. Memory loads automatically.
Multiple sessions run in parallel across different projects and providers. base status shows everything at a glance. base beam sends commands to any session from anywhere.
Every session is captured — messages, tools, tokens, duration. Full transcripts queryable through the API. Agents pick up where they left off, even across provider switches.
Intelligence Layer
Use the right model for the job
Health-checked provider chain with automatic fallback. First healthy provider wins. Switch per-session or let Based route.
Claude
Codex
Gemini
Ollama
intelligence.yaml → priority chain → health check → auto-fallback
Domains
13 queryable domains, one namespace
Every domain is a structured data source with its own schema, filters, and query semantics. Together they form a complete, searchable map of your operation — accessible to humans, agents, and scripts identically.
projects
Auto-discovered bases with git state, tags, lifecycle
sessions
Agent sessions with transcripts, tokens, tools used
Every project, host, agent, and task in Based is described by a single base.md file with YAML frontmatter and a markdown body. That's the contract. The platform refuses to read anything else.
"I never want to have this discussion again."— operator, mid-cutover
The legacy .base.yaml format is gone. 100/100 production bases migrated losslessly to base.md with a single resolver. @based/shared/base-manifest is the only entry point — every reader, writer, and tool routes through it.
Five fail-closed enforcement gates keep it that way: writers refuse non-canonical formats, the API returns 409 on legacy uploads, base doctor blocks startup on manifest issues, CI lints every commit, and a pre-commit hook stops the regression at the developer's machine.
CLIbase manifest Validate, lint, and migrate manifests in place
MCPbased_base_doctor Exposes the manifest gate to agents
# base.md — the only manifest format---name:streaming-infratype:coderealm:prodclaude:auto_start:truecapabilities:required: [tmux, git, claude]
optional: [codex, ollama]
git:host:forgejo# or github---# streaming-infra# Free-form markdown body. The frontmatter is# the source of truth; the body is for humans.
Agent API + MCP
Agents discover the workspace at runtime
One self-describing manifest. Agents read it and know everything Based offers — domains, fields, filters, example queries. No integration code, no adapters, no documentation pass required.
Available as both a REST API and 57 native MCP tools. Same data, same semantics. HTTP for scripts, MCP for agents on the same machine. Every MCP server logs start_request / start_success / stop events to /data/based/state/mcp/lifecycle.jsonl — call based_mcp_health to read instance id, uptime, and recent events.
The Based CLI is the primary interface. Start sessions, query status, send messages, manage memory, audit pain patterns, run diagnostics — all from the terminal.
base start <name>
Launch or resume a tmux session with provider selection
Send keystrokes to any running session in real time
base box
File-drop inbox — async messaging between humans and agents
base msg
Structured mailbox with sequencing and acknowledgment
base mail
Cross-machine mail — peer projects on other hosts
base send
Lower-level send primitive used by msg/mail/beam
base list
All registered projects with type, realm, and status
base new <name>
Scaffold a new base with manifest and structure
base memory
Extract and consolidate session knowledge
base wiki
Ingest, search, and lint structured docs
base clip
Save, search, and recall reusable snippets
base swarm
Orchestrator plan and task control
base manifest
Validate, lint, and migrate base.md manifests
base migrate
Lossless conversion from legacy formats
base audit
Pain-pattern audit over transcripts and telemetry
base doctor
Health + capability gate, runs before every start
base mcp-sync
Push MCP server config to every active session
base telemetry
Inspect lifecycle, audit, and coord-health streams
base flags
View and toggle feature flags
base kill
Stop a session and clean up tmux state
base selftest
End-to-end integration test suite
Orchestrator
Coordinate, don't micromanage
Role-scoped agent coordination. A coordinator plans and delegates. Workers execute. Verification confirms. The loop runs until the work is done.
Plan
Coordinator breaks work into tasks
→
Delegate
Workers receive via mailbox
→
Execute
Workers use role-scoped tools
→
Verify
Results checked against plan
Role-Scoped Tools
Coordinators only get orchestration tools — planning, delegation, messaging. Workers only get execution tools — files, search, git, terminal. Clean separation enforced at the MCP level.
Mailbox IPC
File-backed messaging with sequence numbers and acknowledgment. No HTTP between agents, no shared state. Just JSON lines in a mailbox. Simple, inspectable, debuggable.
11 Specialized Agents
Auditor, pain-auditor, test-author, tester, bug-fixer, fix-proposer, reviewer, frontend-dev, backend-dev, CLI-dev, docs-writer. Real files at .claude/agents/<name>.md. Skills, commands, and hooks per role. Mix and match for any workflow.
Self-Managing Infrastructure
The platform observes, repairs, and gates itself
Based isn't just a workspace agents work in — it's infrastructure that watches itself, audits its own pain patterns, and refuses to start sessions on broken hosts. Three subsystems, all running on every host.
Forgejo — local git vault
Every base auto-mirrors hourly to a local Forgejo at 10.10.10.100:3000 — 76+ bases mirrored as of cutover. LFS and Packages enabled. Pre-push gitleaks scan blocks credential leaks at the developer's machine. Per-base toggle: git.host: forgejo|github. Three MCP tools — based_git_host_status / sync / list — surface mirror state to agents.
Audit pipeline — base audit
Hourly pain-pattern audit over transcripts, mailbox, journal, telemetry, and lifecycle events. 13 pattern classes. Critical findings broadcast to the audit:findings channel so any listener can react. Outputs live at /data/based/state/audit/latest.{json,md}. The pain-auditor agent surfaces patterns; test-author writes regression tests against them.
Bootstrap doctor gate
base doctor --capabilities reads capabilities.required[] / optional[] from base.md and runs before every base start. Per-cap remediation hints. Manifest gate added with the canonical cutover. Sessions don't spawn on hosts that can't support them — the failure happens at the gate, not in the middle of a task.
100/100 production bases on canonical manifest. The convention scales.
Memory
Knowledge that compounds
Per-project memory that persists across sessions, agents, and provider switches. Not chat history — structured, topic-scoped knowledge that gets better over time.
.memory/
├── MEMORY.md— always loaded into context
├── topics/
│ ├── architecture.md— system design decisions
│ ├── deploy-gotchas.md— hard-won lessons
│ ├── preferences.md— coding style, conventions
│ └── debugging.md— past issues and fixes
Sessions become knowledge
Every session generates knowledge. Based extracts it — decisions, gotchas, architectural choices, debugging insights — and files it into topic-scoped memory that loads automatically on the next session start.
Memory isn't locked to one agent or one provider. Switch from Claude to Codex, the memory carries over. Onboard a new agent, it reads the same files. The project remembers, not the model.
Auto-dream mode synthesizes insights during quiet hours. The workspace reflects on itself.
Pairs
Two models. One workspace. Emergent collaboration.
Different models have different strengths. Instead of picking one, pair them. They share the same filesystem, the same messaging system, and the same memory — and they figure out the rest.
Models that complement each other
Run Opus and Codex side by side on the same project. One reasons deeply about architecture. The other executes fast, parallel file changes. They communicate through Based's messaging primitives — mailbox, file drops, shared memory — and naturally start routing work to whoever handles it better.
This isn't a pipeline or a chain. It's co-work — two agents with different minds reading the same codebase, seeing each other's changes in real time, and developing their own communication patterns to lean into their respective strengths.
No special API. No pairing protocol. Just the workspace primitives that already exist for human-agent collaboration — applied to agent-agent collaboration.
base status
❯base status api-refactor opusplanning migration strategy api-refactor codexexecuting file changes (batch 3/5) ❯base msg inbox opus → codex"hold on batch 4 — the auth middleware needs the new types from batch 2 before you touch the routes" codex → opus"acknowledged. running tests on batches 1-3 while you finish the type definitions. ready when you are"
Adaptive Web UI
Three shells. One state. Every screen.
Based's web interface isn't one layout with media queries bolted on. It's three purpose-built shells — compact, tablet, and desktop — each designed for how you actually use that device. Same data, same routes, different surfaces.
📱
Compact Shell
< 640px — phones
Single-pane, bottom tab bar, sheets for secondary content. Check status, read agent updates, send messages, capture notes. Desktop-only features show a placeholder — not a broken miniature.
📋
Tablet Shell
640–1024px — iPads, small laptops
Narrow icon rail + content pane. Slide-over panels replace persistent sidebars. Files and terminal available with touch-aware controls. Right sidebar becomes a sheet, not a crammed column.
🖥️
Desktop Shell
1024px+ — laptops, ultrawides
Full IDE-like 5-column layout. Activity bar, dual sidebars, content area, terminal panel. Ultrawide gets intentional use of extra space instead of stretched emptiness.
Don't shrink — replace
Each shell is a separate component consuming the same Zustand store. When you rotate an iPad from landscape to portrait, the shell swaps — your route, your state, your selected project all survive. Monaco and xterm don't even download on phones. That's not a bug, it's a 3MB bundle win.
Touch-first where it matters
44px minimum tap targets on touch devices. Pointer modality is a first-class axis — an iPad with a trackpad gets desktop density but touch-safe hit areas. Safe-area insets, dynamic viewport units, sheets over modals. The details that make mobile feel native, not adapted.
Typography
Three fonts. Three cognitive modes.
Based's typography isn't aesthetic preference — it's applied cognitive science. Research shows font choice measurably changes memory, focus, and reading behavior. We designed around that.
Aa
Monospace
JetBrains Mono — doing
Headlines, commands, structure. Monospace fonts create desirable difficulty — the brain works harder to process them, encoding content deeper into memory. Every section title sticks because it costs a little more to read.
Diemand-Yauman et al., 2011 — disfluent fonts improve recall by 14%
Aa
Serif
IBM Plex Serif — thinking
Philosophy, descriptions, long-form. Serif fonts increase time spent reading and improve recall over sans-serif. The reflective text on this site uses serif because those are the ideas we want you to sit with.
Gasser et al., 2005 — serif fonts aid recall vs. sans-serif
Aa
Sans-Serif
Inter — navigating
Body copy, UI chrome, card text. Sans-serif fonts are fastest to read on screen — they reduce cognitive load on content that should be transparent. Navigation-level text should inform, not compete for attention.
Kaspar et al., 2015 — sans-serif increases online reading speed
Most tools pick one font and call it a day. Based uses typography as a cognitive layer — monospace for structural memory, serif for reflective depth, sans-serif for speed. The same research applies inside the product: terminal sessions use monospace for retention, wiki pages use serif for comprehension, and UI controls use sans-serif to stay out of your way. Your reading environment is part of the tool.
Theming
Your workspace. Your palette.
Color isn't cosmetic — it's information density. Based ships opinionated defaults and lets you override everything. Accent colors, surface tones, syntax palettes, semantic signals. One config file, applied everywhere.
midnight
default
terminal
green phosphor
opus
purple depth
amber
warm focus
daylight
light mode
theme.yaml
name:my-workspacebase:midnight accent:"#4090ff"surface:"#0a0a0a"border:"rgba(255,255,255,.06)" semantic:success:"#34d399"warning:"#f59e0b"error:"#ef4444"info:"#4090ff" syntax:one-dark# or dracula, catppuccin, nord
🎨 Semantic colors
Success, warning, error, info — mapped to meaning, not arbitrary hex values. Change the accent and every status badge, terminal highlight, and diff gutter updates in sync.
🌗 Surface math
Set one background and Based derives the full surface stack — elevated cards, inset panels, borders, hovers. Perceptually uniform spacing so dark themes don't crush detail.
📦 Syntax palettes
Bring your syntax theme. One Dark, Dracula, Catppuccin, Nord, Solarized — or define your own token map. Applied to Monaco, terminal, and markdown preview simultaneously.
Per-project themes
Drop a theme.yaml in any project. The UI shifts when you switch projects. Opus work in purple, Codex work in cyan — color becomes context.
Time-of-day adaptation
Schedule theme shifts. Cool blue during deep work hours, warm amber at night, full daylight when the sun's up. Your workspace follows your circadian rhythm, not a toggle switch.
Agent identity
Each agent gets a color. When an agent is speaking in the terminal, editing a file, or pushing a status update — its accent color tags the output. You know who did what at a glance.
Local-First
Your tools. Your terminal. No harness.
Based doesn't wrap, proxy, or intercept any AI provider's API. When you start a session, you're running Claude Code, Codex, or Gemini CLI directly in a terminal — exactly as the provider intended. Based just orchestrates the workspace around them.
✓ TOS-Safe
No third-party API access. No token proxying. No subscription workarounds. Providers see normal CLI usage because it is normal CLI usage.
✓ Future-Proof
When providers change their policies, access tiers, or pricing — Based keeps working. It doesn't depend on anything that can be revoked.
✓ Zero Lock-In
Switch providers per-session. Run Claude on one project, Codex on another, local Ollama on a third. Your workspace doesn't care which model is thinking.
Install
One command. macOS and Linux.
Based runs where terminals run. No Electron, no Docker, no containers. Just a binary that orchestrates your existing tools.
install
❯curl -fsSL https://based.md/install | sh detecting platform... darwin-arm64 downloading based v2.0.0... installed to /usr/local/bin/based ❯base doctor ✓tmux 3.4 ✓claude 2.1.92 ✓codex 0.118.0 ✓ollama 0.6.2 ready.
macOS
Intel & Apple Silicon
Linux
x64 & ARM64
Windows
use WSL
Based orchestrates your AI CLIs — it doesn't replace them. Install your providers separately: claude, codex, gemini, or ollama.
Getting Started
Three steps to a shared workspace
Based reads your actual filesystem. No imports, no sync, no migration. Convention-driven discovery means zero setup for new projects.
Declare what exists
Drop a base.md manifest in any project directory. Add hosts to hosts.yaml. Based discovers them automatically. The filesystem is the database.
Based indexes everything
Git repos, sessions, memory files, artifacts, configs, health checks — scanned, parsed, and structured into 13 queryable domains accessible from CLI, API, MCP, and web.
Work together
Start a session. The agent has full context. Send it a message. Read its memory. Query across everything. Same workspace, same tools, same room.