Manifold is a desktop app for running AI coding assistants (Claude Code, Codex, Gemini CLI, and others) side by side on the same codebase. Downloadable releases target macOS; x64 WSL2 is supported through a local source build.
Each agent gets its own git worktree (a separate checkout of the repository on a dedicated branch) when you want isolation, so multiple agents can work on the same repo without branch conflicts. Agents run in real terminals, not wrapper UIs, so you can read and steer their output directly.
Around the terminals, Manifold adds the workspace tools you'd expect: code browsing, diffs, shell tabs, search, previews, commits, and pull requests.
Supported runtimes: Claude Code, Codex, Copilot, Gemini CLI, and Ollama-backed Claude/Codex.
- Run multiple agents in parallel on one repository without branch collisions
- Use the full agent terminal directly, with live streaming output and manual input at any time
- Group several repositories into a Workspace and run one agent across all of them, each repo mounted through the runtime's own multi-directory flag
- Launch work on a new branch, the current branch, an existing branch, or an open pull request
- Spin up a brand-new local web app from a one-line description, scaffolded on a constrained React/Vite stack with a live preview
- Use Viola to plan a goal, fan independent tasks out to isolated runtimes, and cross-review every diff with another runtime
- Run automated Loop cycles that prompt an agent, evaluate the result, and commit on improvement or revert on regression
- Review changes with diffs, a file tree, split editors, shell tabs, and embedded localhost previews
- Search code, file names, captured session memory, or everything at once, with an optional AI mode that answers questions or surfaces the most relevant results
- Keep project state, chat history, dock layout, open files, and shell tabs across restarts
Download the latest .dmg from the GitHub Releases page, open it, and drag Manifold to Applications.
| Requirement | Notes |
|---|---|
| Platform | Downloadable releases target macOS. x64 WSL2 with WSLg supports source builds and local installation. |
| Git | Required for repository management, worktrees, diffs, commits, and pull request flows. |
One supported CLI agent on your PATH |
Manifold checks for the runtime binaries directly. |
GitHub CLI (gh) |
Optional, but required for creating pull requests from inside the app. |
| Ollama + at least one pulled model | Optional, only needed for the Ollama-backed runtimes. |
| Runtime | Binary Manifold looks for | Install | Notes |
|---|---|---|---|
| Claude Code | claude |
claude.com/claude-code | Available in the built-in runtime list. |
| Codex | codex |
github.com/openai/codex | Available in the built-in runtime list. |
| Copilot | copilot |
github.com/github/copilot-cli | Available in the built-in runtime list. |
| Gemini CLI | gemini |
github.com/google-gemini/gemini-cli | Available in the built-in runtime list. |
| Claude Code (Ollama) | ollama |
ollama.com | Launches through ollama launch claude; model selection is required. |
| Codex (Ollama) | ollama |
ollama.com | Launches through ollama launch codex; model selection is required. |
On startup, Manifold reads the PATH from your shell profile and appends common binary directories like ~/.local/bin, /opt/homebrew/bin, and /usr/local/bin so CLIs installed via Homebrew or similar tools are found even when Manifold is launched from Finder.
Before launching Manifold, confirm the prerequisites are reachable from your shell:
git --version # any recent Git
gh --version # optional, needed for pull request creation
claude --version # or: codex --version / gemini --version / copilot --versionIf a runtime command is not found, install it (see the links above) and make sure its binary is on your PATH.
Manifold supports x64 WSL2 with WSLg. Windows-native, ARM64 Linux, downloadable Linux releases, and Linux auto-updates are not supported.
# Required native build tools
sudo apt update && sudo apt install -y build-essential python3 ripgrep git
# Recommended (for full prompt features — bash works too)
sudo apt install -y zsh
# Node.js 22.12+ via nvm: https://github.com/nvm-sh/nvmgit clone https://github.com/vippsas/manifold.git && cd manifold
npm install
./install-linux.sh # builds linux-unpacked and installs a launcher in ~/.local/binEnsure ~/.local/bin is in your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrcnpm run devRequires WSLg (ships with Windows 11 22H2+). The installer keeps the unpacked application under ~/.local/share/manifold; rerun it to update. "Open in Terminal" uses the distro's x-terminal-emulator command, which must be a GNOME-family terminal that accepts --working-directory (for example gnome-terminal); a terminal that rejects that flag (such as xterm) reports an error instead of opening.
Manifold opens straight into its full developer workspace — a panelled layout you can rearrange to suit your workflow. The current panel set includes:
- Repositories sidebar
- Agent terminal
- Search
- File tree
- Modified files
- Shell tabs
- Web preview
- One or more editor panes
Key workflows:
- Open an existing local repository or clone one from GitHub
- Start an agent on a fresh worktree branch (branches are named
<repo>/<task-slug>automatically, for examplemanifold/fix-login-bug) - Start an agent directly on the current branch when you do not want a worktree
- Continue work from an existing branch or from an open pull request
- Resume a stopped agent in place
- Generate commit messages and pull request descriptions using the same agent runtime the session used
- Detect merge conflicts and see how many commits your branch is ahead of or behind the base branch
A Workspace groups several repositories into one working set so a single agent can operate across all of them at once.
- Workspaces are opt-in: enable Settings → General → Enable Workspaces to add working-set cards to the left sidebar; leaving it off preserves the standard repository-only workflow
- The sidebar is a flat list of bordered working sets: a repository starts as a one-repository box, and its folder-plus action promotes it to a workspace where you can add more repositories
- The first repository is the agent's working directory; the others are mounted through the runtime's own multi-directory flag (
--add-dirfor Claude, Codex, and Copilot;--include-directoriesfor Gemini) - When the agent starts, Manifold creates a worktree for every git repository in the set, all on the same branch (
manifold/<workspace-name>by default), and removes them again when the session ends - Every workspace has its own visible name. Add or remove repositories directly from its card; every box stays open, and the New Agent action opens a modal without replacing the current agent view
- Each agent row has a settings gear for renaming the agent and reviewing its runtime, mode, and branch; the previous deletion-lock control is no longer shown
Workspaces are useful when a task spans several repositories at once — for example, landing a change that touches both a backend and a frontend repo, or running the same refactor across many services. A workspace agent sees every included repository from the start; there is no orchestration layer or per-tool approval step in between.
When no project is selected, the sidebar offers Start from scratch (and Start from copied instructions) to create a brand-new local web app from a one-line description:
- Manifold creates a project folder under your storage directory (
~/.manifold/projects/...) and tracks it automatically - An agent scaffolds and iterates on the app, constrained to a local stack: React 19, TypeScript, Vite, Dexie/IndexedDB (browser-local database), and CSS Modules
- It runs
npm installandnpm run devso the live preview comes up immediately - You keep iterating through a chat panel while previewing the app, with the full terminal, diff, and git tools always one click away
This flow is intended for local prototyping and iteration. Deployment is not implemented.
-
Open a local repo using the Add Project button, or clone one from the welcome screen.
-
Pick a project in the sidebar.
-
Launch an agent with a task description, for example:
Add input validation to the login form and write unit tests for the new checks.
-
Watch output in the terminal, steer it manually when needed, and review changes in the editor and diff views.
-
Commit from the status bar and open a pull request through
ghwhen the branch is ready.
A new agent can start in four ways:
- New branch: the default path, using a dedicated git worktree
- Current branch: runs directly in the project checkout, without creating a separate worktree
- Existing branch: continue work already in progress
- Open pull request: select an open pull request, check out its branch, and continue work from there
Agent states shown in the UI: running (actively working), waiting (paused for input), done (finished successfully), and error (stopped on failure).
Choose Viola from the ordinary New agent screen when a goal can be split into independent, PR-sized tasks. It opens as a normal agent tab, proposes a plan, and waits for approval. Enter the goal as a normal chat message, then choose Start plan or Revise plan in Viola's reply. The plan tags each task as an implement task or a read-only explore task and lists the gate commands that must pass. Once started, every task runs as its own pipeline: an implement task gets a managed worktree on one of the installed Claude, Codex, Copilot, or Gemini runtimes, its gates run before any review, and a different runtime then reviews the contract and diff from a scratch worktree with the diff applied. Each worker is a real terminal in its own tab, so you can watch one or take it over mid-run; only Viola itself is a chat agent. One red-gate fix and one blocking-review fix go back to the original implementer; explore tasks simply report back. Viola narrates each step in its chat and never merges. It needs at least two of those runtime binaries installed to preserve independent review, and it needs a repository added as a git project: a plain folder is worked in place, which leaves no way to isolate a task or review it independently.
The Loop dock panel runs an automated improve-and-evaluate cycle on an agent session:
- Prompt the agent with your instruction
- Run a user-defined evaluation command
- Extract a numeric score from the result — a process exit code, a regex match on stdout, a field from JSON output, or an LLM judge
- Commit the changes if the score improved, or discard them and revert to the previous state if it regressed
- Repeat until you stop it or the maximum number of iterations is reached
Each iteration has a configurable time limit; if the agent exceeds it, Manifold stops it automatically. Results are logged per worktree under ~/.manifold/loop-logs/. The panel tracks the best score so far and offers Restore Best to jump back to the commit that produced it.
The workspace includes a search system that goes beyond file text search.
- Search modes:
code(file contents),files(file names),memory(captured session data), oreverything(code and memory together) - Search scopes: the current session, all sessions for the current project, or across all registered projects — depending on mode
- Match modes: literal or regex
- Saved searches and recent searches are persisted per project
Ask AIcan answer questions using the retrieved results as context, or re-sort exact matches by relevance, depending on settings
Manifold also captures session data locally and stores it per project in SQLite:
- interactions — prompts sent and responses received
- observations — facts the agent noted during a session
- session summaries — compressed overviews used when resuming long sessions
That memory is used for search and to give the agent relevant history when a session is resumed.
By default, Manifold stores its state under ~/.manifold/.
| Path | Purpose |
|---|---|
~/.manifold/config.json |
User settings (storage path, default runtime, theme, etc.) |
~/.manifold/projects.json |
Registered projects (name, path, base branch) |
~/.manifold/memory/*.db |
Per-project SQLite memory stores |
~/.manifold/loop-logs/*.jsonl |
Automated Loop iteration logs (one file per worktree) |
~/.manifold/debug.log |
Debug log — check here first when something goes wrong |
~/.manifold/worktrees/... |
Managed git worktrees (default location) |
~/.manifold/projects/... |
Locally generated app projects (default location) |
The storage root (~/.manifold by default) is configurable in Settings → Storage Path.
- Node.js 22.12+
- npm
- macOS, or x64 WSL2 with WSLg and the native build tools listed above
- Git
- At least one supported CLI runtime installed locally
git clone https://github.com/vippsas/manifold.git
cd manifold| Command | Purpose |
|---|---|
npm install |
Install dependencies. Run once after cloning, and again when package.json changes. |
npm run dev |
Launch Electron in development mode with hot reload via electron-vite. Auto-rebuilds native modules. |
npm start |
Run the built app locally. Also auto-rebuilds native Electron modules. |
npm run build |
Produce a production build of main, preload, and renderer bundles. |
npm run dist |
Build and package a macOS .dmg for distribution. |
npm run dist:linux |
Build the x64 Linux unpacked directory without publishing it. |
npm run verify:linux-package |
Verify the Linux executable and packaged native modules. |
npm run typecheck |
Run the web, node, and plugins typechecks 832D below. |
npm run typecheck:node |
Typecheck main process, preload, and shared code (tsconfig.node.json). |
npm run typecheck:web |
Typecheck renderer and shared code (tsconfig.web.json). |
npm run typecheck:plugins |
Typecheck plugin sources under resources/plugins (tsconfig.plugins.json). |
npm test |
Run the full vitest suite once. |
npm run test:watch |
Run vitest in watch mode while iterating on tests. |
Before opening a pull request, make sure npm run typecheck and npm test both pass.
Manifold follows Electron's multi-process model, where the UI has no direct access to Node.js or the filesystem — all system calls go through a controlled bridge:
src/main/: terminal processes (PTYs), git/worktree operations, workspaces, search, memory, settings, and app lifecyclesrc/preload/: the bridge layer — whitelists which Node.js operations the UI is allowed to callsrc/renderer/: the developer workspace UI, including the draft-chat app-builder flowsrc/renderer-shared/: chat components shared across renderer surfacessrc/shared/: shared types, defaults, prompts, and theme data
For a subsystem-by-subsystem map of the main process — sessions, worktrees, runtimes, memory, search, plugins, and the rest — see the contributor documentation map.
For security, embedded web previews are limited to localhost URLs only — they cannot load external sites.
Contributions are welcome. A quick outline:
- Fork the repo and create a branch from
main. - Follow the Local Development steps to get the app running.
- Make your change, keeping it focused and small where possible.
- Run
npm run typecheckandnpm test— both must pass. - Open a pull request describing the change and the testing you ran.
See CONTRIBUTING.md for the full contributor setup, code conventions, test commands, and pull request workflow.
Manifold is released under the MIT License. See LICENSE for the full text.
Releases happen in two steps so the version bump lands on main before the tag is created.
- Prepare the release PR (choose one based on the change):
./release.sh patch # bug fixes and small changes
./release.sh minor # new features, backwards compatible
./release.sh major # breaking changes- After that PR is merged, publish the release:
./release.sh publish