One workspace. Same terminal, same filesystem, same context. Multi-provider AI orchestration that treats collaboration as the primitive, not the feature.
Not a wireframe, and not a raw screenshot. This compresses the real browser shell into one readable moment: the human asks, agents coordinate, the terminal moves, files change, and memory updates in the same workspace.
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
$based_agent_contact to=claude intent=request codex asks: stage a visual mockup for the website ok mailbox write seq=118 wake=ping_attempted
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
messagescoordination visible
humanCan we translate the browser into a visual mockup?
codexReading the real UI, staging one workflow in based-web.
claudeReview requested for tone and accuracy.
memoryloaded into context
.memory/MEMORY.md
Visual direction: use the real browser app as source of truth, but stage a single product moment. Screenshots prove it later; the hero should make it instantly understandable.
01Human asks
The request appears in the same workspace the agents use.
02Agents wake
Peers, tools, context, and safety constraints are visible.
03Work happens
The terminal, files, diff, and mailbox move together.
04Status returns
The human sees what changed and what is ready next.
Philosophy
The best collaboration doesn't need a handoff — it happens in the same room.
Most AI tools create a boundary: humans work here, agents work there, and something translates between them. Based removes the boundary entirely.
Humans and agents share the same terminal sessions, navigate the same filesystem, query the same 13 structured domains, and communicate through the same messaging primitives. There's no integration layer because there's nothing to integrate — it's one workspace.
Projects discover themselves through convention. Infrastructure declares itself in YAML. Sessions capture themselves automatically. Memory compounds across conversations. The workspace is the interface.
When you work in Based, you're not managing AI — you're working with it. Same context, same tools, same room.
Co-Work
Everything is shared
Based doesn't separate human workflows from agent workflows. Every surface is designed for both.
Humans + Agents
Shared Terminal
Real PTY sessions where humans type commands and agents send keystrokes into the same tmux pane. Broadcast mode syncs input across all sessions. No simulator, no sandbox — the real terminal.
Humans + Agents
Shared Filesystem
Convention-driven project discovery. Drop a manifest in any directory and it exists. Both humans and agents navigate the same tree, edit the same files, read the same configs.
Agents
Self-Describing API
Agents read one manifest and discover every domain, field, filter, and query pattern at runtime. No documentation needed, no custom adapters. Also available as 57 native MCP tools.
Humans
Web Explorer
21-mode dashboard with file explorer, session browser, infrastructure map, terminal grid, notes, memory, logs, usage analytics, and kanban. Keyboard-driven. Everything agents see, you see.
Humans
Flow Triggers
Queue the tracks that put you in the zone. Not a streaming service — a focus tool. Three songs on repeat for six hours. You know the ones. Built into the workspace because deep work isn't just code — it's state of mind.
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.