new-feature

new-feature aims to eliminate friction for creating new features. In a single command, it creates isolated git worktrees, allocates conflict-free runtime values, runs project-defined setup and teardown commands (such as creating and deleting a feature database), and optionally launches a configured coding agent in the new worktree.

Install

uv tool install new-feature
new-feature setup --agent codex

new-feature setup launches the configured coding agent in the current repository. With no local default agent yet, pass --agent codex or --agent claude. The agent inspects the project, proposes a repository-specific configuration, asks about unresolved choices such as the optional Codex hook, and waits for approval before further edits. Run it again to review and improve an existing integration.

Documentation

The documentation site uses this README as its homepage and generates its API reference from package docstrings. Build it before committing documentation changes:

uv run mkdocs build --strict

To preview the site locally with live reload, run uv run mkdocs serve. Pushing to main builds and deploys the site through GitHub Pages.

Usage

# Ask an agent to configure or improve new-feature for this repository.
new-feature setup --agent codex
# Create a feature worktree. It launches no agent unless you configure a local default.
new-feature my-feature
# Create a feature worktree and explicitly launch an agent.
new-feature my-feature --agent claude
# Create a feature worktree without launching an agent, even when a default is configured.
new-feature my-feature --no-agent
# Merges the worktree into the main branch
new-feature merge my-feature
# Run configured teardown and remove the feature worktree.
new-feature teardown my-feature
# Teardown a worktree even if it has uncommitted work.
new-feature teardown my-feature --force
# Inspect managed features and diagnose stale state.
new-feature list
new-feature doctor
new-feature doctor --repair

Project Config

Put shared repository policy in the target repo's .new-feature.toml:

target_branch = "main"
setup = ["uv sync"]
pre_merge = ["uv run pytest"]
post_merge = ["uv run pytest"]
teardown = []

[env]
WEB_PORT = { allocate = "port", min = 3000, max = 3999 }
API_PORT = { allocate = "port", min = 4000, max = 4999 }
DATABASE_NAME = { allocate = "name", prefix = "myapp", max_length = 63 }
CACHE_DIR = { allocate = "path", base = ".new-feature/cache" }

Keep personal preferences in the ignored .new-feature.local.toml sidecar:

default_agent = "codex"
pull_before_create = true
push = true
agents = { custom = ["custom-agent", "--prompt"] }

new-feature setup and feature creation ensure that *.local.toml is in .gitignore. This makes local agent commands, automatic pull/push preferences, and machine-specific values safe to customize without changing versioned repository policy.

All settings remain optional. new-feature resolves a shared configuration from .new-feature.toml when present, otherwise from [tool.new-feature] in pyproject.toml. It then overlays .new-feature.local.toml, which uses the standalone-file syntax above and can also be used on its own. A local value replaces a shared scalar or command list; entries in agents and env overlay by name. For projects that prefer the shared pyproject.toml form, use [tool.new-feature.env] there and [env] in the local sidecar.

default_agent, pull_before_create, and push remain supported in shared config when a repository wants to enforce them, but local placement is the recommended default. default_agent is optional: without it, feature creation does not launch an interactive agent. Codex and Claude are built in and always work with --agent; agents adds or overrides named commands and fixed arguments. new-feature appends its generated feature prompt as the final argument, so a personal agent that requires a prompt flag can be configured in the local sidecar:

# .new-feature.local.toml
default_agent = "custom"
agents = { custom = ["custom-agent", "--prompt"] }

Use a configured agent for one invocation, or pass an executable command directly:

new-feature my-feature --agent claude
new-feature my-feature --agent "fooagent --baz-flag"
new-feature setup --agent claude

When the value exactly matches a key in agents, that configured command is used. Otherwise, new-feature parses the value as an executable command without invoking a shell.

The built-in create and setup prompts can be overridden with create_prompt and setup_prompt in TOML, or for one invocation with --prompt.

setup runs after worktree creation; teardown runs before worktree removal.

Supported env entries:

• { value = "literal" }
• { allocate = "port", min = 3000, max = 3999 }
• { allocate = "integer", min = 1, max = 15 }
• { allocate = "name", prefix = "myapp", max_length = 63 }
• { allocate = "slug", prefix = "myapp" }
• { allocate = "path", base = ".new-feature/cache" }

Lifecycle

new-feature my-feature creates branch my-feature and worktree .worktrees/my-feature, reserves env values in .new-feature/manifest.toml, runs setup, and launches an agent only when default_agent or --agent selects one. With pull_before_create = true, it first runs a fast-forward-only pull on the clean, checked-out target branch. It automatically adds .new-feature/, .worktrees/, and *.local.toml to .gitignore. If setup fails or is interrupted, it stops the command's process group and runs a forced teardown so the partial worktree, branch, manifest entry, and child processes do not linger.

Running create again for an active feature reuses its recorded worktree and environment, skips pulling, allocation, and setup, and launches the selected agent again. Dry runs also skip pulling. Without a selected agent, it prints the existing worktree guidance. If the recorded worktree or branch is missing, create stops and directs you to new-feature doctor --repair instead of silently replacing inconsistent state.

After a successful create that does not launch an agent (for example, with --no-agent or no selected agent), new-feature prints the absolute worktree path and a copy-pasteable command such as:

Worktree ready: /path/to/repository/.worktrees/my-feature
Next: cd -- /path/to/repository/.worktrees/my-feature

A CLI process cannot change its parent shell's or an already-running coding agent's working directory. In an interactive shell, run the printed cd command; an existing coding agent should use the printed absolute path as the working directory for its subsequent tools. Paths on the Next: line are shell-quoted when necessary.

new-feature list shows each managed feature and its current Git/worktree state, including patch-equivalent when every non-merge patch already exists in the target history despite different commit ancestry. new-feature doctor reports stale manifest entries, dirty worktrees, unmerged branches, and configuration drift. doctor --repair removes stale manifest entries whose worktree and branch are both already gone, and recovers a missing worktree when its branch is merged or patch-equivalent.

new-feature merge my-feature first requires a clean feature worktree and rejects a predicted conflict, before it runs pre-merge checks. Different features can run those checks in parallel, but a second merge or teardown for the same feature fails while its lifecycle is in progress. Merges serialize before validating or changing the shared target checkout. The command then rechecks the conflict under that lock, starts a no-commit merge into the target branch, runs post-merge checks on the merged target checkout, commits the merge only if those checks pass, records the merge, and pushes only when push = true. A failure through the bookkeeping step stops the command process group and restores the target's original clean revision, including removing generated untracked files. A push failure leaves the successful local merge recorded; rerun the same merge command to retry only the push. Failed pre- and post-merge commands retain their combined output under .new-feature/diagnostics/merge-failures/<feature>/; the error prints the exact log path.

new-feature teardown my-feature runs the configured teardown commands before removing the worktree, deleting the branch, and removing the manifest entry. If the manifest does not know the feature, teardown still recognizes the conventional .worktrees/my-feature path, derives its actual branch, and applies the same Git safety checks. It skips configured teardown commands for that fallback because their recorded environment is unavailable. Merged and patch-equivalent branches are safe to remove normally. If the worktree has uncommitted changes, the branch has patches absent from the target history, or an unmanaged worktree is detached, pass --force to abandon it deliberately. Branch ranges containing merge commits remain unmerged because git cherry cannot account for novel conflict resolutions.

Agent hooks

Install the Codex or Claude Code hook in the current repository:

new-feature install-codex-hook
new-feature install-claude-hook

The Codex hook is written to .codex/hooks.json; Codex loads the guard only for this trusted repository. The Claude Code hook is written to the hooks section of .claude/settings.json, which Claude Code loads at session start. Both guards protect the configured target branch from direct agent edits and require Git worktree creation and removal to go through the managed new-feature lifecycle.

Both installers accept --global to install the guard in the user-level configuration (~/.codex/hooks.json or ~/.claude/settings.json) so it covers every repository on the machine; outside a new-feature-managed repository the guard allows everything. The Claude Code installer also accepts --local to write the guard to .claude/settings.local.json, the personal gitignored settings file, instead of the shared settings.json.