codrift

Codrift

Drive multiple AI coding agents across your projects from one desktop app.

Codrift is a desktop app for running Claude Code, Codex, Opencode, Gemini, Copilot, Cursor, and shell agents side-by-side. You group directories into initiatives, launch agents against each one, watch their output live in embedded terminals, review diffs, and let them share knowledge through a built-in memory store.

Codrift is a Tauri app: a native window wrapping a Svelte UI, backed by an Elixir (Francis) server that manages agents, worktrees, memory, and integrations.

---

Features

• Native desktop app — sidebar + live agent terminals (xterm.js), keyboard-driven, on macOS and Linux
• Multiple agents per directory — Claude Code, Codex, Opencode, Gemini, Copilot, Cursor, and a raw terminal shell, all running simultaneously
• Git worktrees — each directory gets an isolated branch; agents never touch your main checkout
• Live diff view — colour-coded split/unified diff per initiative, updated as agents work
• Tree view — mode 3 shows a file-tree browser with syntax-highlighted previews and an in-app editor
• Shared memory — FTS5 knowledge base per initiative; agents search it before starting, write to it when done
• MCP server — Claude Code and other tools connect to Codrift and call its tools over SSE
• External integrations — pull context from GitHub, Linear, and GitLab
• Session persistence — Claude sessions survive restarts; agents resume where they left off
• Context folders — each initiative has ~/.codrift/initiatives/{id}/ picked up automatically by --add-dir

---

Quick start

Homebrew (macOS)

This repo is its own Homebrew tap. Because the repo isn't named homebrew-codrift, tap it once with its URL, then install the cask:

brew tap filipecabaco/codrift https://github.com/filipecabaco/codrift
brew install --cask codrift

That installs Codrift.app and the headless codrift command, so codrift mcp install works straight after. It is one download: the command is a symlink into the app bundle, whose sidecar is a complete release of the same code and runs the CLI when handed arguments. Upgrades move both:

brew upgrade codrift

Installed the old codrift-cli formula? Remove it with brew uninstall codrift-cli — it shadows the cask's command on PATH and keeps reporting its own version. The formula is gone from the tap; brew used to download the same ~15 MB release twice because of it.

For headless boxes, CI or Linux, where there is no app to link into, take the codrift-cli-<version>-<target>.tar.gz from the release and extract it, or run the installer below — it does the same thing.

Note: Codrift is not yet code-signed or notarized. The cask strips the download quarantine on install so the app opens normally; if macOS still objects, right-click the app → Open once, or run xattr -dr com.apple.quarantine /Applications/Codrift.app.

Direct download

Grab the latest bundle for your platform from GitHub Releases:

Platform	Bundle
macOS	.dmg
Linux	.AppImage / .deb

From source

mix deps.get
cd assets && npm install && cd ..
mix ex_tauri.install   # first time only — sets up the Tauri toolchain
mix ex_tauri.dev       # launch the app with hot reload

Then register the MCP server so Claude Code can talk to Codrift:

codrift mcp install
# runs: claude mcp add codrift --transport http http://localhost:43117/mcp \
#         --header "X-Codrift-Token: <token from ~/.codrift/auth-token>"

---

Core concepts

Initiatives

An initiative is a named unit of work — a feature, bug fix, or project milestone. Each initiative holds one or more project directories and tracks its own status (planning → ongoing → done → archived). Everything — agents, memory, worktrees, integrations — lives under an initiative.

codrift initiative create "auth redesign"
codrift initiative add-dir <id> ~/projects/backend
codrift initiative add-dir <id> ~/projects/frontend

Git worktrees

Codrift can create a git worktree on a dedicated branch (codrift/{id}/{slug}) for any directory in an initiative. Agents operate there and their changes stay isolated until you're ready to merge.

Enable a worktree from the CLI (codrift initiative worktree-enable <id> <path>), or set worktree_default on an initiative so new directories inherit it. See docs/worktrees.md.

Shared memory

Each initiative has a searchable knowledge base (SQLite FTS5). Agents write decisions, summaries, and code snippets to it; new agents search it before starting work — saving tokens and keeping them aligned across sessions.

codrift memory search <id> "authentication"
codrift memory add    <id> decision "use JWT not sessions"
codrift memory recent <id>

Agents can also call these as MCP tools (memory_search, memory_add, …). See docs/memory.md.

MCP server

While Codrift is running, an MCP server listens at http://localhost:43117/mcp (streamable HTTP; /mcp/sse also serves clients that only speak the older HTTP+SSE transport). State-changing requests authenticate with the local token from ~/.codrift/auth-token (sent as an X-Codrift-Token header — codrift mcp install configures this automatically). Any connected agent can call:

Category	Tools
Initiatives	list_initiatives, create_initiative, add_dir, delete_initiative, set_initiative_status, get_diff
Agents	list_agents, start_agent, send_to_agent, get_agent_output
Memory	memory_search, memory_add, memory_delete, memory_recent, memory_list
Integrations	start_oauth_flow, get_oauth_status, list_integration_items, import_from_integration, sync_initiative_context

Agent skills

The MCP server hands agents the tools; the skills in skills/ teach them when to reach for one — search the shared memory before exploring, check what sibling agents are touching, write findings back so the next session starts ahead.

npx skills add filipecabaco/codrift        # add -g to install for every project

Or run Setup from the command palette (⌃P) — Codrift opens a terminal and runs both this and codrift mcp install for you, so you never leave the app.

Skill	Covers
codrift	The workspace model every other skill builds on
codrift-memory	The shared FTS5 store: what to record, what not to
codrift-initiatives	Directories, lifecycle, worktree branches, combined diffs
codrift-orchestration	Spawning agents, fan-out, the conductor, orchestration.md
codrift-integrations	GitHub, Linear and GitLab: OAuth, listing, importing, syncing

Installs into Claude Code, Codex, Cursor, Gemini CLI, Copilot and Opencode.

---

Keyboard reference

Global

Key	Action
j / k / ↑ / ↓	Navigate sidebar
1 / 2 / 3	Context / Diff / Tree view
r	Refresh initiatives & agents
Ctrl+P	Command palette
Ctrl+B	Collapse / expand sidebar
⇅ in the sidebar header	Order initiatives by created / recent / name / status
⌘D / ⌘⇧D	Split the focused pane right / down — repeatable, nesting, auto-balanced
⌘W	Close the focused pane
⌘K	Clear the focused terminal (macOS)
Ctrl+,	Settings — workspace folder, appearance, launch profiles, integrations
Ctrl+Q	Quit

Initiatives & agents

Key	Action
n	New initiative
Ctrl+N	Open a scratchpad in the directory under the cursor — unnamed, rankable up later
a	Add directory to initiative
s	Start a Claude agent in the directory under the cursor
t	Start a raw $SHELL terminal in the directory under the cursor
d	Delete or stop (context-sensitive)
o	Start orchestration for the selected initiative
p	Change which agent (or launch profile) this initiative starts
f / g / m / u	Git: fetch / rebase / commit / push (acts on the worktree)
[ / ]	Cycle initiative status

Use the Launch dropdown next to a directory (or the palette) to start Codex, Opencode, Gemini, Copilot, or Cursor — or p to set the initiative's agent from the keyboard.

Context, tree & editor

Key	Action
e	Open the selected file in the editor (Vim mode — :w / ⌘S to save)
Tab	Focus the terminal (or return to the sidebar from the tree)
⌘Esc	Return focus to the sidebar — the terminal keeps Tab for completion
Shift+Enter	Newline in the agent prompt instead of submitting
⌘-click	Follow a URL in agent output, in your default browser

All keys are configurable in ~/.codrift/keybindings.json. See docs/keyboard.md for the full reference.

---

External integrations

Pull issue context directly into an initiative from:

GitHub Issues · GitHub Projects · Linear Issues · Linear Projects · GitLab

codrift integration auth github       # OAuth2 browser flow
codrift integration list github       # list open issues
codrift integration import github 42  # seed an initiative from issue #42

Both OAuth (PKCE / device flow, handled in-app) and personal API token fallbacks are supported. No secrets are stored in the binary. See docs/integrations.md.

---

CLI reference

The desktop app is the primary interface. A headless CLI ships alongside it for scripting and MCP registration:

codrift start          # launch the desktop app
codrift mcp install

codrift initiative list
codrift initiative create <name>
codrift initiative add-dir <id> <path>
codrift initiative delete  <id>
codrift initiative worktree-status  <id>
codrift initiative worktree-enable  <id> <path>
codrift initiative worktree-disable <id> <path>

codrift memory search <id> <query>
codrift memory add    <id> <type> <content>
codrift memory recent <id>
codrift memory list   <id> <type>
codrift memory delete <id> <rowid>
codrift memory stats  <id>

codrift integration services
codrift integration auth   <service>
codrift integration list   <service>
codrift integration import <service> <item_id>
codrift integration revoke <service>
codrift integration tokens

---

Screens

Context	Diff	Tree

Also: the command palette, shared memory, and integrations.

---

Documentation

Architecture · Keyboard reference · Tree view · Diff mode · Worktrees · Memory · Integrations · Agent profiles · Modules · Decisions

---

Architecture

Tauri window (Rust)  ── spawns ──▶  Elixir sidecar ("desktop" release)
   Svelte UI (xterm.js)                Codrift (Application)
        │  HTTP + WS  :43117              └── Codrift.Supervisor (:one_for_one)
        └───────────────────────────────────┤ Registry (AgentRegistry)
                                             ├── Codrift.Initiative.Store
                                             ├── Codrift.SessionStore (SQLite)
                                             ├── Codrift.OAuth.StateStore
                                             ├── Codrift.AgentSupervisor
                                             │     └── Codrift.AgentProcess (erlexec PTY)
                                             ├── {Task.Supervisor, Codrift.TaskSupervisor}
                                             ├── Codrift (Francis / Bandit) — HTTP + WS
                                             └── Codrift.ShutdownManager (desktop only)

See docs/architecture.md and docs/modules.md.

---

Development

mix deps.get
unbuffer mix test        # full test suite
mix credo --strict
mix dialyzer

mix ex_tauri.dev         # run the desktop app with hot reload
mix ex_tauri.build       # produce a platform bundle

Stack: Elixir · Francis · ex_tauri · Svelte · xterm.js · SQLite (Exqlite) · erlexec

Supported platforms

Platform	Target
macOS (Apple Silicon)	aarch64-apple-darwin
macOS (Intel)	x86_64-apple-darwin
Linux x86_64	x86_64-linux-gnu
Linux arm64	aarch64-linux-gnu

Releasing

Releases are fully automated from Conventional Commit prefixes — there is nothing to tag by hand. On every merge to main, release.yml inspects the commits since the last v* tag and bumps semver accordingly:

Commit prefix	Bump	From 0.0.0
fix:	patch	0.0.1
feat:	minor	0.1.0
feat!: / major: / BREAKING CHANGE	major	1.0.0

The highest-priority prefix in the range wins; commits with no fix/feat/breaking prefix (chore:, docs:, …) don't release. From there the same workflow builds the macOS .dmgs + Linux bundles + CLI, cuts the v<version> tag and GitHub Release, and rewrites Casks/codrift.rb with the new version and checksums. To cut a specific version by hand, run Release via Run workflow and type the version; leave it empty to just re-derive it from the commits.

The version in mix.exs and src-tauri/tauri.conf.json is a placeholder — the workflow stamps the real number in before building. Git tags, not committed files, decide what ships.

---

License

MIT