Worktrees & Plan Mode

noumen includes tools for structured planning workflows: plan mode restricts the agent to read-only operations, while worktrees provide isolated git branches for parallel or experimental work.

Plan mode

Why opt-in?

Plan mode adds two tools (EnterPlanMode, ExitPlanMode) that let the agent switch itself into a read-only state. This changes the agent's permission model at runtime, which may be surprising if you're not expecting it — the agent could enter plan mode mid-task and stop making progress. The extra tools also add to the context cost of every request.

Configuration

const code = new Agent({
  provider,
  sandbox,
  options: {
    enablePlanMode: true,
  },
});

Tools

When in plan mode, the permission system automatically denies write operations. The agent can still read files, search, and use other read-only tools.

Git worktrees

Why opt-in?

Worktree tools create real git worktrees on disk, which has filesystem and git side-effects beyond the normal sandbox scope. The agent might create branches and directories you don't expect. Keeping this opt-in ensures worktrees are only used when you've designed your workflow around them.

Configuration

const code = new Agent({
  provider,
  sandbox,
  options: {
    enableWorktrees: true,
  },
});

Tools

How it works

1. EnterWorktree creates a worktree via git worktree add on a new branch
2. The agent's working directory is switched to the worktree
3. Changes are isolated from the main branch
4. ExitWorktree returns to the original directory and optionally cleans up

Utility functions

The worktree module also exports utility functions for programmatic use:

import {
  findGitRoot,
  createWorktree,
  removeWorktree,
  listWorktrees,
  getWorktreeChanges,
  sanitizeWorktreeSlug,
} from "noumen";