new-feature 0.3.0

Create isolated feature worktrees with allocated runtime environments.

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 launches the configured coding agent in the new worktree.

Install

uv tool install new-feature

Or copy and paste this into your favorite coding agent:

Run curl -fsSL https://pypi.org/pypi/new-feature/json, read info.description, and set up new-feature on this machine.

Usage

# Create a feature worktree and launch the configured agent.
uvx new-feature my-feature
# Create a feature worktree without launching another agent.
uvx new-feature my-feature --no-agent
# Merges the worktree into the main branch
uvx new-feature merge-feature my-feature
# Run configured teardown and remove the feature worktree.
uvx new-feature teardown my-feature
# Teardown a worktree even if it has uncommitted work.
uvx new-feature teardown my-feature --force
# Inspect managed features and diagnose stale state.
uvx new-feature list
uvx new-feature doctor
uvx new-feature doctor --repair

Project Config

Add config to the target repo's pyproject.toml:

[tool.new-feature]
target_branch = "main"
branch_prefix = "feature/"
agent = ["codex"]
push = false
setup = ["uv sync"]
pre_merge = ["uv run pytest"]
post_merge = ["uv run pytest"]
teardown = []

[tool.new-feature.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" }

agent is the command and arguments used to launch the coding agent. new-feature appends its generated feature prompt as the final argument, so agents that require a prompt flag can be configured directly:

[tool.new-feature]
agent = ["copilot", "--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 .worktrees/my-feature, reserves env values in .new-feature/manifest.toml, runs setup, and launches the configured agent in the worktree. It automatically adds .new-feature/ and .worktrees/ to .gitignore. If setup fails, it runs a forced teardown so the partial worktree, branch, and manifest entry do not linger.

new-feature list shows each managed feature and its current Git/worktree state. new-feature doctor reports stale manifest entries, dirty worktrees, unmerged branches, and configuration drift. doctor --repair removes only manifest entries whose worktree and branch are both already gone.

new-feature merge-feature my-feature runs pre-merge checks in the feature worktree, 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, and pushes only when push = true.

new-feature teardown my-feature runs the configured teardown commands before removing the worktree, deleting the branch, and removing the manifest entry. If the worktree has uncommitted changes or the branch has commits that are not in the target branch, pass --force to abandon them deliberately.