Key concepts

If you understand one thing about Octopush, make it this page.

Projects → Workspaces → Modes

Octopush is built on a three-level model:

• A Project is your repository.
• A Workspace is a git worktree branched off that repository, with an AI assigned to it.
• Each Workspace gives you the modes — Talk, Run, Review, and optionally Direct.

The analogy: a Workspace is a git branch with an AI assigned; a Project is the repo.

Project (your repository)
│
├── Workspace A  ──  worktree + assigned AI
│     ├── Talk    (chat)
│     ├── Run     (terminal)
│     ├── Review  (diff + git)
│     └── Direct  (pipelines, optional)
│
├── Workspace B  ──  worktree + assigned AI
│     ├── Talk
│     ├── Run
│     ├── Review
│     └── Direct
│
└── Workspace C  ──  worktree + assigned AI
      ├── Talk
      ├── Run
      ├── Review
      └── Direct

Each workspace is its own isolated working copy of the project. Work in one never bleeds into another.

Why worktrees

A git worktree is a second (third, fourth…) working directory attached to the same repository, each on its own branch. Octopush uses worktrees so every workspace is truly parallel and isolated:

• You can have an agent refactoring in Workspace A while another writes tests in Workspace B — at the same time, with no conflicts.
• The terminal, the diff, and the chat in a workspace all see the same files, untouched by anything happening elsewhere.
• Throwing away a workspace is cheap: it’s just a worktree.

Tip

This is the payoff of the model. Traditional editors force one working tree, so parallel agent tasks step on each other. Worktrees give each task its own ground.

The modes

Every workspace exposes the same set of modes, all operating on that workspace’s worktree:

• Talk (⌘⇧1) — chat with the model, with live token and cost tracking.
• Run (⌘⇧2) — a real PTY terminal that survives restarts.
• Review (⌘⇧3) — unified diff, embedded editor, and git status.
• Direct (⌘⇧D) — multi-agent pipelines.

Talk, Run, and Review are always present. Direct is optional and enabled per workspace — turn it on when a task needs multiple agents chained together; leave it off otherwise.

How it fits together

Because all modes share one worktree, the workflow loops naturally: ask in Talk, execute in Run, inspect in Review, and reach for Direct when one agent isn’t enough. Switch workspaces with ⌘1–⌘9 to jump between parallel tasks.

Next

See the keyboard shortcuts to move through all of this quickly.