┌─────────────────────────────────────────────────┐
│                    You / Agent                   │
├──────────┬──────────┬───────────┬───────────────┤
│   CLI    │  Web UI  │  MCP      │  REST API     │
│  base *  │ :3333    │  20 tools │  /api/*       │
├──────────┴──────────┴───────────┴───────────────┤
│              based-api (:3334)                    │
│  12 domain adapters · agent query · orchestrator │
├──────────────────────────────────────────────────┤
│              Filesystem (DATA_ROOT)              │
│  bases · sessions · memory · config · telemetry  │
├──────────────────────────────────────────────────┤
│           Intelligence Providers                  │
│  Claude CLI · Codex CLI · Gemini CLI · Ollama    │
└──────────────────────────────────────────────────┘

Installation

macOS and Linux. One command.

Quick install

curl -fsSL https://based.md/install | sh

Detects your platform (darwin-arm64, darwin-x64, linux-x64, linux-arm64), downloads the binary, and installs to /usr/local/bin/based.

Alternative: npm

# npm
npm install -g @based/cli

# bun
bun add -g @based/cli

Verify

base doctor

Checks for required dependencies:

Dependency	Required	Notes
tmux	Yes	Session orchestration backbone
git	Yes	Per-base state tracking
node	Yes	v22+ for API server
claude	At least one	Claude Code CLI
codex	At least one	OpenAI Codex CLI
gemini	At least one	Google Gemini CLI
ollama	Optional	Local model inference

Platform support

Platform	Status
macOS (Apple Silicon)	✅ Primary
macOS (Intel)	✅ Supported
Linux (x64)	✅ Supported
Linux (ARM64)	✅ Supported
Windows	❌ Use WSL

Quick Start

First session in 2 minutes.

1. Initialize a base

# In any project directory
base new myproject

Creates a base.md manifest. Based discovers it automatically on the next scan.

2. Start a session

base start myproject

Launches a tmux session with your preferred AI provider. Based auto-selects from the intelligence chain, or you can specify:

base start myproject --provider claude
base start myproject --provider codex

3. Check status

base status

Cross-project dashboard showing active sessions, dirty repos, inbox items, and provider health.

4. Query across everything

# CLI (via API)
curl -s "http://localhost:3334/api/agent/query?q=deploy" -H "Authorization: Bearer $TOKEN"

# MCP (from any connected agent)
based_query({ query: "deploy" })

Searches all 12 domains in parallel — projects, sessions, files, git, logs, memory, config, and more.

5. Open the web UI

# Default: http://localhost:3333
open http://localhost:3333

Full IDE-like interface with 19 navigation modes, Monaco editor, integrated terminal, and real-time filesystem sync.

Core Concepts

The ideas that make Based work.

Bases

A base is any directory with a base.md manifest. It's the atomic unit of Based — a project, a service, a set of docs, a task. Based discovers bases by scanning DATA_ROOT and its subdirectories.

# base.md frontmatter
---
name: my-api
type: code
realm: production
tags: [api, express, deployed]
lifecycle: active
priority: high
---

# my-api
Express backend for the main product.
## Notes
- Deployed to .11
- Uses PostgreSQL

Convention over configuration

Based uses typed subdirectories under DATA_ROOT:

• code/ — source code projects
• host/ — infrastructure configs
• agent/ — agent definitions
• space/ — workspaces and planning
• task/ — task-scoped work

Drop a directory in the right place with a base.md, and Based picks it up. No registration, no imports, no config files.

Sessions

Sessions are real tmux terminal sessions where AI providers run. Based discovers sessions from provider-specific stores:

• ~/.claude/projects/**/*.jsonl — Claude Code
• ~/.codex/sessions/YYYY/MM/DD/*.jsonl — Codex
• ~/.gemini/sessions/*.jsonl — Gemini

Every session has token counts, tool call history, and timing metadata — all queryable from the API.

The filesystem is the database

Based doesn't use a database. Project manifests, memory files, config, mailbox messages, telemetry — everything is a file. This means:

• Git tracks all changes automatically
• Any editor can modify any data
• Agents read and write directly — no ORM, no migration
• Backup is rsync

Agent-first design

Every API endpoint returns structured, typed data. The Agent API (/api/agent/) is self-describing — one call returns every domain, every field, every filter, and example queries in natural language. Any agent can understand the entire platform without reading documentation.

CLI Reference

18 commands. All terminal-native.

The base command dispatches to base-<cmd> scripts. All commands share helpers from base-lib (path resolution, telemetry, hooks).

Sessions

Command	Alias	Description
base start <name>	s	Launch or resume a tmux session with provider selection
base kill <name>	k	Stop a session (runs post-kill hooks)
base list	ls, l	List all registered bases
base status	st	Cross-project dashboard

Project

Command	Alias	Description
base new <name>	n	Scaffold a new base with manifest
base migrate	mig	Convert .base.yaml → base.md
base migration	—	Run data migration operations

Messaging

Command	Alias	Description
base box	bx	File-drop inbox
base inbox	in	Inbox management
base msg	—	Structured JSONL mailbox (send/inbox/ack/broadcast)
base beam	send	Send keystrokes to tmux sessions

System

Command	Alias	Description
base doctor	—	Health and dependency checks
base selftest	test	End-to-end integration suite
base docs	d	Generate shell aliases for ~/.bashrc
base telemetry	tele	View CLI usage analytics
base flags	flag	View/set feature flags

Orchestration

Command	Alias	Description
base swarm	—	Orchestrator plan + task controls
base memory	—	Memory extraction + consolidation

Shell Aliases

Generated by base docs --apply.

b    → base
bl   → base list
bs   → base status
ho   → base inbox
bd   → base doctor

Realm wrappers

Based provides realm-aware credential wrappers for common CLIs:

wr <cmd>    → Wrangler (Cloudflare), injects token by realm
aw <cmd>    → Appwrite, switches profile by realm
gh-wrap <cmd> → GitHub CLI, switches account by realm

Realm mapping is configured in cli-profiles.yaml.

System Architecture

Two services, one filesystem, many providers.

Services

Service	Port	Scope	Description
based-api	3334	Loopback only	Express + MCP server. Domain adapters, agent query, orchestrator, mailbox.
based-web	3333	All interfaces	Express + React SPA (Vite). File ops, terminal, search, git, explorer. Proxies /api/based/* to based-api.
@based/shared	—	Library	Shared errors, logger, path/validation helpers, intelligence query.

WebSockets

• /ws — real-time filesystem change events (file create/update/delete)
• /ws-terminal — interactive terminal I/O (shell access from the browser)

Proxy architecture

based-web sits in front. Browser calls hit :3333, which strips Origin headers and injects the bearer token before forwarding to :3334. The browser never sees the API token.

Deploy model

Based separates development and production onto different machines. Edits happen on dev, deploys push to production via rsync, and builds always happen on the target machine (never locally) to avoid chunk hash drift between environments.

Data Layer

The filesystem is the database.

Canonical roots

DATA_ROOT=/data              # default
BASED_SCAN_ROOTS=/data       # discovery paths

Typed subdirectories:

• code/ — source code projects
• host/ — infrastructure configs
• agent/ — agent definitions
• space/ — workspaces and planning
• task/ — task-scoped work

Base manifests

Canonical format is base.md — markdown with YAML frontmatter:

---
name: my-project
type: code
realm: production
tags: [api, express]
lifecycle: active
completion: 0.7
priority: high
assignee: tree
depends_on: [shared-lib]
custom:
  deploy_target: ".11"
---

# my-project
Project description and notes here.

Legacy .base.yaml is still supported. Use base migrate to convert.

Global config

Lives in /data/based/config/:

File	Purpose
.env	Secrets, ports, paths
flags.yaml	Feature flags
cli-profiles.yaml	Realm → credential mapping
hosts.yaml	Infrastructure inventory
intelligence.yaml	AI provider chain + health
basedrc	Shell config
tmux.conf	tmux session config
telemetry.jsonl	Unified append-only telemetry

Per-base artifacts

.claude/
  agents/*.md          — agent definitions
  skills/*/SKILL.md    — reusable skills
  commands/*.md        — slash commands
  settings.json        — hooks, permissions, shortcuts
  hooks/               — pre/post-tool-use scripts
.mcp.json              — per-base MCP server config
.memory/
  MEMORY.md            — memory index
  topics/*.md          — topic-scoped memory files

12 Domains

Everything is queryable.

Based organizes all data into 12 domain adapters. Each domain is searchable individually or via cross-domain fan-out (/api/agent/query). Each adapter has a 5-second timeout; partial failures are surfaced in data.errors.

Domain	Description
projects	Discovered bases — name, path, type, realm, tags, lifecycle
sessions	Provider sessions with token/tool metadata (Claude, Codex, Gemini)
artifacts	CLAUDE.md, agents, rules, commands, hooks, skills, MCP configs
git	Status, branch, recent commits per base
logs	Service + tmux logs, searchable
memory	MEMORY.md + topic files per base
config	Base manifests (frontmatter fields)
health	Node + service state
views	Artifact aggregation (shared scanner)
usage	Token + cost analytics across providers
files	File listing + content (parallel per-project scan, budget-limited)
hosts	Infrastructure inventory from hosts.yaml

Cross-domain search

# Search across all 12 domains
GET /api/agent/query?q=deploy

# Response shape
{
  "results": [...],
  "errors": [...],
  "meta": {
    "byDomain": {
      "projects": 3,
      "files": 12,
      "git": 5,
      ...
    }
  }
}

REST API

Full endpoint reference.

based-api (port 3334)

Agent API

Method	Path	Description
GET	/api/agent	Self-describing manifest — every domain, field, filter
GET	/api/agent/query?q=	Cross-domain fan-out search
GET	/api/agent/:domain	List per domain
GET	/api/agent/:domain/:id	Entity detail
GET	/api/agent/projects/:name/full	Multi-domain aggregate for one project

Core

Method	Path	Description
GET/POST	/api/bases	Manifest CRUD + stats
GET	/api/hosts	Infrastructure inventory from hosts.yaml
GET	/api/based/sessions	Provider session discovery
GET	/api/based/sessions/stats	Session summary
GET	/api/based/sessions/:id/messages	Session message history
GET	/api/based/sessions/:id/tools	Session tool call history
GET	/api/based/status	Live base status summary
GET	/api/based/logs	Log search
GET	/api/based/usage	Token + cost stats
GET	/api/based/views	Artifact aggregation
*	/api/messages	Mailbox + ack (seq model)
*	/api/notes	Markdown note CRUD
*	/api/orchestrator	Plans, tasks, verification, memory/dream
GET	/api/intelligence	Providers + health + query
*	/api/claude-accounts	Account management
GET	/api/system	Diagnostics + telemetry

based-web (port 3333)

File operations

Method	Path	Description
GET	/api/files/content	Read text file
GET	/api/files/raw	Stream binary with Content-Type
GET	/api/files/list	Flat file listing
POST	/api/files/write	Write file
POST	/api/files/move	Move/rename
POST	/api/files/mkdir	Create directory
POST	/api/files/upload	Upload file
DELETE	/api/files/	Delete file

Explorer + Search

Method	Path	Description
GET	/api/explorer/:baseId/list?path=	Lazy directory listing
GET	/api/explorer/__all__/list	All registered bases
GET	/api/explorer/:baseId/artifacts	Claude artifact discovery
GET	/api/search	Content search
GET	/api/git	Status, branch, history

Other

Method	Path	Description
*	/api/terminal	Terminal session control
*	/api/kanban	Board persistence
*	/api/templates	Template CRUD
GET	/api/music	Local track control
GET	/api/processes	tmux process summary
GET	/api/cli-tools	Detected binaries + health
GET	/api/system	Host metrics, telemetry, CLI detection

Authentication

Bearer token, timing-safe.

API token

# Get a token
TOKEN=$(curl -s -X POST http://localhost:3334/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"pin":"YOUR_PIN"}' | jq -r '.token')

# Use it
curl -s http://localhost:3334/api/agent/ \
  -H "Authorization: Bearer $TOKEN"

Web proxy

The web frontend at :3333 handles auth transparently — it strips Origin headers and injects the bearer token before forwarding to the API. The browser never sees the raw token.

Security model

• Bearer token with timing-safe comparison (no timing attacks)
• API server binds to loopback only (:3334) — not reachable from network
• Path validation: base-path containment checks reject directory traversal
• File APIs surface all entries (including dotfiles) — no hidden policy, full transparency

MCP Server

20+ tools for native agent access.

Based exposes a Model Context Protocol server that any MCP-compatible agent can connect to. Same data as the REST API, native tool interface.

Search & Query

Tool	Description
based_query	Cross-domain search, returns results grouped by domain
based_files_search	File name + content search
based_memory_search	Memory topic search
based_logs_search	tmux + service log search

Projects & Sessions

Tool	Description
based_projects_list	All registered bases
based_project_full	Multi-domain aggregate for one project
based_sessions_list	Claude/Codex/Gemini sessions
based_artifacts_list	Agents, skills, commands, hooks, MCP configs
based_git_status	Git state per base

Infrastructure

Tool	Description
based_health_check	Node + service health
based_hosts_list	Infrastructure inventory

Config & Views

Tool	Description
based_config_get	Project manifest
based_views_list	View/artifact aggregation
based_usage_stats	Token + cost stats

tmux

Tool	Description
based_tmux_list	Active sessions
based_tmux_send	Send keystrokes to a session
based_tmux_broadcast	Send to all sessions

Mailbox

Tool	Description
based_msg_send	Enqueue message
based_msg_inbox	Read messages for participant
based_msg_ack	Acknowledge up to sequence number
based_msg_broadcast	Send to all participants

Intelligence

Tool	Description
intelligence_query	Prompt with provider fallback
intelligence_providers	List providers + status
intelligence_health	Health check all providers

System

Tool	Description
based_system_guide	Full platform reference document

Web Frontend

19 modes. Three shells. One state.

What's in it

• File explorer — lazy-loaded tree with Monaco code editor
• Terminal — full interactive shell (tmux sessions from the browser)
• Session browser — see every AI session, token usage, tool calls
• Kanban — persistent boards for task tracking
• Notes — markdown scratch space
• Memory browser — view/search agent memory topics
• Real-time sync — filesystem changes appear instantly via WebSocket

Adaptive shells

The web UI uses three physical shell components instead of one responsive layout:

• CompactShell (<640px) — single pane, bottom tab bar, sheets for secondary content
• TabletShell (640–1024px) — icon rail, slide-over panels
• DesktopShell (1024px+) — full 5-column IDE layout, ultrawide-aware

All three consume the same Zustand store. Shared state, distinct rendering. Desktop-only features render a placeholder on compact — not a broken miniature.

Navigation Modes

19 modes across 5 sidebar sections.

Explorer

• Home — dashboard with 7 widgets (alive-now, needs-attention, where-left-off, quick-launch, ai-brief, provider-status, recent-activity)
• Files — lazy tree + Monaco editor + git context
• Sessions — provider session browser with token/tool detail
• Bases — registered project list with status

Infrastructure

• Hosts — infrastructure inventory from hosts.yaml
• Processes — tmux process summary
• CLI Tools — detected binaries, profiles, health

Agents

• Views — artifact aggregation (agents, skills, commands)
• Templates — template CRUD
• Kanban — board persistence
• Mailbox — message inbox (#/messages alias)

Workspace

• Terminal — groups/panes, broadcast mode, quick command launch
• Notes — markdown notes
• Memory — memory topics browser

Analytics

• Logs — service + tmux log search
• Usage — token + cost dashboards
• Status — live system status

Special

• Recent — 3-column recent files
• Settings — app configuration (Ctrl+,)

Keyboard shortcuts

Key	Action
Ctrl+0	Home
Ctrl+1..9	Mode switch
Ctrl+,	Settings
Ctrl+`	Toggle terminal
Ctrl+B	Toggle left sidebar
Ctrl+Shift+B	Toggle right sidebar
Ctrl+K	Global search
Ctrl+Shift+N	Quick note
F11	Focus mode
? / Ctrl+/	Shortcut help

Terminal

tmux is the workspace. Based gives you a window into it.

Every Based session is a tmux session. When you run base start, it creates a tmux session, launches your AI provider inside it, and wires up the context. When you run base beam, it sends keystrokes to that tmux session. When you run base kill, it stops it. tmux is the backbone — Based orchestrates on top of it.

The web UI gives you access to these sessions from the browser. You can launch sessions, watch their output, type into them, split into panes, and broadcast commands — all without leaving the Based interface.

Launching sessions

The fastest way to start working is the Quick Command panel in the right sidebar. Pick a base and a provider, click, and you're in a session:

# From the CLI:
base start myproject                    # auto-select provider
base start myproject --provider claude  # specific provider
base start myproject --provider codex   # or codex, gemini, ollama

Sessions persist independently of the browser — close the tab, come back later, the tmux session is still running. Reattach from the web UI or from your local terminal with tmux attach.

Panes and layouts

Split the terminal view into multiple panes to watch several sessions at once:

• Groups — up to 2 panes per group, unlimited groups
• Grid mode — maximize to see all panes at once (2-up, L-layout, or auto-grid)
• Per-pane focus — click a pane to focus it, the rest stay visible

Broadcast mode

Toggle broadcast to type the same input into every pane simultaneously — useful for running the same command across multiple projects or providers at once.

Beam (remote keystrokes)

Send commands to any tmux session without switching to it:

base beam myproject "npm test"    # type into a specific session
base beam --all "git pull"        # broadcast to every session

This is how agents communicate in real-time — beam is one of the three messaging pathways alongside Box and Msg.

Context sidebar

When the terminal is active, the right sidebar shows Quick Commands — one-click launch buttons organized by base × provider. No typing base start every time.

Agent System

8 specialists. Skills, commands, hooks.

Based ships with 8 specialized agent definitions in .claude/agents/. Each agent gets a focused role, relevant context, and appropriate tool access.

Specialized agents

Agent	Role
auditor	Codebase audits, gap analysis, compliance
tester	Playwright + integration tests
bug-fixer	Root-cause analysis + targeted fixes
reviewer	Code review against project standards
frontend-dev	React / TypeScript / Tailwind
backend-dev	Express / Node / API work
cli-dev	Bash / CLI scripting
docs-writer	Reference documentation

Supporting artifacts

• .claude/skills/*/SKILL.md — reusable skill invocations
• .claude/commands/*.md — slash commands for interactive use
• .claude/settings.json — hooks, permissions, shortcuts
• .claude/hooks/ — pre/post-tool-use scripts (approval gates, logging)

Intelligence Layer

Multi-provider. First healthy wins.

Based doesn't pick a provider for you — it runs a prioritized chain defined in intelligence.yaml. When you query, the first healthy provider handles it. If it fails, the next one catches it.

Provider chain

Priority	Provider	Notes
1	Codex	Primary for code work
2	Gemini	Secondary
3	Claude	Via CLI wrapper
4	Ollama	Local inference

Health checking

Providers are health-checked asynchronously with TTL-cached results. Disabled or unhealthy providers are skipped automatically. Monitor via:

# API
GET /api/intelligence

# MCP
intelligence_providers()
intelligence_health()

Direct selection

base start myproject --provider claude
base start myproject --provider codex

Orchestrator Mode

Coordinator + workers + verification. Feature-flagged.

The orchestrator enables multi-agent coordination with role-based tool scoping. It's behind feature flags — enable when ready.

How it works

1. Coordinator creates a plan with discrete tasks
2. Workers execute tasks with scoped tool access
3. Verification step validates each completed task
4. Communication happens via the mailbox system

Role-scoped tools

When role_scoped_tools flag is enabled:

Role	Tools
observer	Read-only query tools
worker	Task execution tools
coordinator	Planning + orchestration tools only (never touches files)

Feature flags

• coordinator_mode — enable the coordinator role
• role_scoped_tools — restrict tools by agent role
• verify_execution — require verification after task completion

CLI

base swarm          # orchestrator plan + task controls
base swarm plan     # create a new plan
base swarm tasks    # list tasks
base swarm verify   # run verification

Memory System

Persistent context across sessions.

Each base gets a .memory/ directory that persists across sessions. Agents read from it automatically; Based indexes it for search.

Structure

.memory/
  MEMORY.md          — index file, always loaded into context
  topics/
    deploy.md        — deployment notes and procedures
    gotchas.md       — hard-won debugging lessons
    preferences.md   — coding style and conventions
    architecture.md  — design decisions and rationale

Pipeline

• base memory — manual extraction + consolidation
• Auto-dream (feature-flagged: auto_dream, auto_memory_extract) — background pipeline that synthesizes sessions into memory topics automatically

Search

# MCP
based_memory_search({ query: "deploy procedure" })

# API (via agent query)
GET /api/agent/memory?q=deploy

Messaging

Box. Msg. Beam. Three pathways.

Based has three messaging systems, each for a different use case. No HTTP between agents — everything is filesystem or tmux.

Box (file drop)

Drop anything into a base's inbox/ directory. Markdown, images, links, data files. The simplest possible messaging — it's a folder.

base box myproject          # open inbox
base box myproject note.md  # drop a file

Msg (structured mailbox)

JSONL append-only files per participant under /data/based/state/mailbox/. Sequence + acknowledge model — receivers mark messages as processed.

base msg send alice "review the deploy script"
base msg inbox              # read your messages
base msg ack 5              # acknowledge through seq 5
base msg broadcast "standup at 2pm"

Also available via API (/api/messages) and MCP (based_msg_*).

Beam (real-time tmux)

Send keystrokes directly to a tmux session. Real-time, zero latency, no intermediary.

base beam myproject "npm test"   # type into session
base beam --all "git pull"       # broadcast to all

Pairs

Two agents. One project. Emergent routing.

Pairs is not a feature — it's a behavior that emerges from Based's existing primitives. When two AI providers work the same project, they communicate through the shared filesystem and mailbox system. Over time, they start routing tasks to each other based on strengths.

How it works

1. Start two sessions on the same base with different providers
2. They share: filesystem, .memory/, mailbox, git state
3. Msg and Box handle coordination — no orchestrator needed
4. Each provider develops a model of the other's strengths

base start myproject --provider claude   # session 1
base start myproject --provider codex    # session 2

# They communicate via:
base msg send codex "review the auth module"
base box myproject findings.md

Why it works

Different models have genuinely different strengths. Opus excels at architecture and nuanced decisions. Codex is faster at file-level edits and test writing. When they can communicate, they self-organize around these strengths without being told to.

Deploy Pipeline

deploy.sh — sync, build, restart.

Based includes a deploy script (deploy.sh) for syncing between development and production machines. It handles the full lifecycle: commit dirty changes, rsync to the target, build on the remote, restart services, and verify health.

Commands

./deploy.sh all        # full deploy: shared → config → cli → api → web
./deploy.sh shared     # sync + build @based/shared library
./deploy.sh config     # sync config files only
./deploy.sh cli        # sync CLI scripts, chmod +x
./deploy.sh api        # sync + remote build + restart based-api
./deploy.sh web        # sync + remote build + restart based-web
./deploy.sh health     # verify API + web are responding
./deploy.sh pull       # pull remote changes back to dev

Workflow

1. Edit on your dev machine
2. deploy.sh auto-commits any dirty changes before syncing
3. Sync to production via rsync
4. Build on the production machine (never locally — avoids chunk hash drift)
5. Restart services via systemd and verify via health endpoint

Feature Flags

Ship incrementally. flags.yaml.

Flag	Description	Default
coordinator_mode	Enable orchestrator coordinator role	off
role_scoped_tools	Restrict MCP tools by agent role	off
mailbox_ipc	File-backed mailbox messaging	on
worktree_isolation	Git worktree per session	off
auto_memory_extract	Auto-extract memory from sessions	off
auto_dream	Background reflection/consolidation	off
context_compaction_v2	v2 compaction algorithm	off
verify_execution	Require verification after tasks	off

# View flags
base flags

# Set a flag
base flags set coordinator_mode true

Configuration

Convention-driven. Minimal config.

Environment

# /data/based/config/.env
DATA_ROOT=/data
BASED_SCAN_ROOTS=/data
API_TOKEN=your_token_here
PORT_API=3334
PORT_WEB=3333

basedrc

Shell configuration sourced by the CLI:

# /data/based/config/basedrc
export BASED_SCAN_ROOTS="/data"
export BASED_CONFIG_DIR="/data/based/config"

hosts.yaml

Infrastructure inventory:

hosts:
  - name: gpu-server
    ip: 10.0.0.10
    role: proxmox
    specs: "64 cores, 192GB RAM"
  - name: inference
    ip: 10.0.0.20
    role: inference
    specs: "128GB DDR5, local models"

intelligence.yaml

Provider chain:

providers:
  - name: codex
    priority: 1
    enabled: true
  - name: gemini
    priority: 2
    enabled: true
  - name: ollama
    priority: 4
    endpoint: "http://localhost:11434"
    enabled: true

Telemetry

Append-only. Local-only. Your data.

Based logs usage events to a single JSONL file. No external services, no analytics platforms. The data stays on your machine.

Sources

Events are collected from three surfaces, all appending to the same file:

• CLI — every base command, session start/stop
• API — deploy events, per-route instrumentation
• Web UI — navigation, file saves, searches, messaging

Event types

Source	Events
CLI	cli_command, session_started, session_ended
API	deploy_started, deploy_completed, per-route instrumentation
Web	tab_viewed, file_saved, search_performed, box_sent, msg_sent, beam_sent

Read

GET /api/system/telemetry?period=24h   # last 24 hours
GET /api/system/telemetry?period=7d    # last week
GET /api/system/telemetry?period=all   # everything

base telemetry                          # CLI view

The recent-activity homepage widget is the live visualization of this data.

Flow Triggers

Your workspace knows deep work isn't just code — it's state of mind.

What it is

Based includes a built-in audio player designed for one thing: getting into flow state. This isn't a music app. There's no library browser, no recommendations, no social features. You queue a few tracks you already know work for you, hit play, and forget about it for hours.

Why it's in a dev tool

Research supports what deep workers already know intuitively: intentional music selection — choosing specific tracks to regulate your cognitive state — has a direct positive effect on performance (PMC, 2023). Not background noise. Not Spotify's algorithmic playlist. The three songs you've listened to 400 times that flip the switch in your brain.

The key finding: autonomous control over music (choosing what, when, and why) is what drives the benefit. That's why it's built in. You stay in your workspace. No alt-tab, no context switch, no notification from a streaming app breaking your concentration.

CLI

# Queue tracks
base play add ~/flow/boards-of-canada-roygbiv.mp3
base play add ~/flow/tycho-awake.mp3

# Control playback
base play              # start / pause
base play skip         # next track
base play loop         # toggle loop mode (track / queue / off)
base play status       # what's playing, queue depth, loop mode
base play clear        # empty the queue

Design principles

• Minimal surface. Queue, play, pause, skip, loop. That's it. If you want equalizers and crossfade, use a music app.
• Local files only. No streaming integration, no API keys, no accounts. Your MP3s, your FLAC files, your WAVs. Drag from Finder, paste a path, done.
• Loop-first. Default behavior is queue loop. Most flow state usage is the same 2–5 tracks on repeat for an entire session. The player assumes that.
• No interruptions. No "up next" popups, no end-of-track silence, no notifications. Gapless playback. The audio is infrastructure, not an experience.
• Session-scoped. Your queue lives with your Based session. Different projects can have different flow tracks. Start a session, your flow tracks are already there.

Web UI

The web frontend includes a minimal player bar at the bottom of the workspace — track name, progress, play/pause, skip, loop toggle. It stays out of the way. Click to expand for queue management. Collapse and it's a single 32px bar.

The philosophy

Based treats the human operator as a first-class citizen. Agents get memory, messaging, orchestration. Humans get those too — plus the tools that sustain long sessions. Flow triggers exist because the workspace should support the whole workflow, not just the code part.

Three songs on repeat for six hours. You know the ones.

Known Gotchas

Hard-won lessons.

If you're using Based

• $TMUX in the web terminal — if base start from the web UI tries to switch your existing tmux instead of creating a new session, make sure $TMUX is unset in the terminal's shell environment. Based handles this automatically, but custom shell configs can re-set it.
• YAML numbers — YAML parses 3334 as a number, not a string. If you're comparing ports or IDs in manifests, be aware that "3334" !== 3334.
• Build on the production machine — always run builds on the deploy target, not locally. Vite chunk hashes differ between machines, which breaks browser caching.
• ESM imports need .js extensions — if you're writing plugins or extending Based, all TypeScript imports must include .js in the import path. TS compiles but doesn't rewrite them.

If you're contributing to Based

See docs/HARD-WON-FIXES.md in the repo for the full developer gotchas list (pino version pinning, symlink handling in readdir, localStorage migration patterns, etc.).

Philosophy

Why Based exists.

Local-first

Your tools. Your terminal. Your filesystem. No cloud dependency, no account required, no data leaves your machine. Based runs on your hardware and uses your existing AI subscriptions through their official CLIs. When a provider changes their terms, you switch — Based doesn't care which model you use.

Terminal-native

The terminal is the workspace, not a feature of the workspace. tmux sessions are real, processes are real, file edits are real. The web UI is a window into the terminal world, not a replacement for it.

Convention over configuration

Drop a base.md in a directory. That's it. No registration, no database migration, no config files beyond the manifest. Based discovers, indexes, and serves.

Agent-first, human-usable

Every API is designed for agents to discover and use at runtime. But every interface also works for humans — the CLI is fast, the web UI is full-featured, the docs are readable. The best tools serve both.

Co-work, not automation

Based doesn't automate humans out of the loop. It puts humans and agents in the same workspace with shared context, shared tools, and transparent communication. The human decides what matters; the agents help execute.