Codans

Parallel development for the agent era.
One Mac-native window. Many worktrees. Every agent.

Codans is a terminal development environment built for parallel development with coding agents. It orchestrates all of your projects, worktrees, and coding agents into a single window.

Highlights


Native	Built on Ghostty and native to macOS.
Agent-first	See the live running state of every agent in real time.
Parallel	Project tree + git worktrees + tabs + split panes manage every line of work in one window. No more Cmd-Tab.
Custom commands	Bind project-specific commands and shortcuts; one chord runs the right thing.
GitHub	Deep GitHub integration — manage the whole pull-request lifecycle in-app.
Keyboard-driven	A deep set of customizable shortcuts to keep you fast.
IDE integration	VS Code, Cursor, Zed, and Xcode are auto-detected. One shortcut opens any worktree.

Install

brew install --cask wanggang316/tap/codans

The cask installs Codans.app into /Applications and symlinks the embedded codans CLI into Homebrew's bin. Subsequent updates flow through the in-app Sparkle updater; brew upgrade --cask codans also picks up new stable releases.

Running Codans

Requires macOS 14 (Sonoma) or later. Xcode and mise are only needed to build
from source.

Open Codans and add a project directory from the sidebar.
Select its root worktree, or create a worktree for a separate line of work.
Run a coding agent in the terminal; use tabs and split panes for parallel tasks.

For CLI usage, see the Agent Skill.

Build from Source

Development requirements

Xcode 26.0+ (pinned via apps/mac/Tuist.swift)
mise for tool version pinning (tuist, zig, swiftlint, xcbeautify, xcsift)

Generate, build, and run

# One-time per worktree
mise trust . apps/mac
make bootstrap            # init submodules (ghostty, git-wt) + mise install

# Generate + build + run
make mac-generate         # tuist install + tuist generate (builds Ghostty xcframework)
make mac-build            # build Codans.app + codans CLI
make mac-run-app          # build + open the app

First-time Ghostty build is ~3.9 GB / ~20 min. In additional worktrees, symlink the cache:
ln -s <main>/apps/mac/.build/ghostty apps/mac/.build/ghostty

Development commands

Command	Description
`make bootstrap`	Init submodules + `mise install`
`make mac-generate`	Generate `codans.xcworkspace` from Tuist
`make mac-build`	Build the Mac app + `codans` CLI
`make mac-run-app`	Build and launch `Codans.app`
`make mac-lint`	Run `swiftlint --quiet`
`make mac-check`	`swift-format` in-place + lint
`make mac-test`	Run the Codans, CodansCore, and CodansKit test schemes
`make mac-release`	Archive → notarize → DMG → staple
`make help`	Full target list

The top-level Makefile delegates every mac-* target to apps/mac/Makefile.

Documentation

All project knowledge lives in docs/:

Architecture — domains, layers, dependency rules
Product spec — what the product is
Design docs — feature and system designs

Agent-facing entry point: AGENTS.md (also exposed as CLAUDE.md).

License

Codans is open source under the MIT License.