agentctl

agentctl

A CLI tool for managing Claude Code configurations, hooks, and isolated workspaces using git worktrees.

Features

• Workspace Management: Create isolated git worktree-based workspaces for parallel Claude Code sessions
• Hook Integration: Seamless integration with Claude Code lifecycle hooks
• Auto-commit: Automatic git commits on feature branches for Edit/Write operations
• Context Injection: Live git/workspace status injected into every Claude prompt
• Notification System: macOS notifications with automatic agent detection (Claude Code, Cursor, Cursor Agent)
• Tab Completion: Intelligent tab completion for workspace commands

Installation

Via Go Install

go install github.com/ryantking/agentctl/cmd/agentctl@latest

Download Binary

Download the appropriate binary for your platform from the latest release.

Extract and place the binary in your PATH (e.g., /usr/local/bin or ~/bin).

Quick Start

# Check installation
agentctl status

# Show version
agentctl version

# Initialize Claude Code configuration
agentctl init

# Create a new workspace
agentctl workspace create my-feature-branch

# List all workspaces (with tab completion!)
agentctl workspace list

# Show workspace details
agentctl workspace status my-feature-branch

# Delete a workspace
agentctl workspace delete my-feature-branch

Commands

Workspace Commands

Manage git worktree-based workspaces for parallel development sessions.

• agentctl workspace create <branch> [--base <branch>] - Create new workspace with git worktree
• agentctl workspace list [--json] - List all workspaces (includes main/master, shows current with *)
• agentctl workspace show [branch] - Print workspace path (for shell integration)
• agentctl workspace status [branch] - Show detailed workspace status
• agentctl workspace delete [branch] [--force] - Delete a workspace
• agentctl workspace clean - Remove all clean workspaces

Tab Completion: Workspace commands (show, status, delete) support tab completion for branch names.

JSON Output: Use --json flag on any workspace command for programmatic access:

agentctl workspace list --json
agentctl workspace show refactor/golang --json

Hook Commands

Hook commands are designed to be called from Claude Code hooks. They handle stdin parsing, error handling, and exit codes appropriately.

• agentctl hook inject-context - Inject git/workspace context into prompts
• agentctl hook notify-input [message] - Send notification when input is needed
• agentctl hook notify-stop - Send notification when a task completes
• agentctl hook notify-error [message] - Send error notification
• agentctl hook post-edit - Auto-commit Edit tool changes
• agentctl hook post-write - Auto-commit Write tool changes (new files)

Notification Agent Detection: Notifications automatically detect the agent environment and use the appropriate icon:

• Cursor Agent (TUI): Detected via CURSOR_AGENT=1 and CURSOR_CLI_COMPAT=1
• Cursor IDE: Detected via CURSOR_AGENT=1 (without CURSOR_CLI_COMPAT)
• Claude Code: Detected via CLAUDECODE=1

You can override the sender with AGENT_NOTIFICATION_SENDER environment variable.

Init Command

Initialize Claude Code configuration in a repository or globally.

• agentctl init - Initialize Claude Code configuration
  • --global - Install to $HOME/.claude instead of current repository
  • --force - Overwrite existing files
  • --no-index - Skip Claude CLI repository indexing

Other Commands

• agentctl version - Show the current version
• agentctl status - Show the status of Claude Code installation
• agentctl completion [bash|zsh|fish|powershell] - Generate shell completion scripts

Development

Prerequisites

• Go 1.24+
• just (command runner)
• golangci-lint (for linting)
• gofumpt (for formatting)
• govulncheck (for vulnerability checking)
• macOS (for full feature support, including notifications)

Setup

# Install system dependencies
just deps

# Install globally
just install

# Run tests
just test

# Run linter
just lint

# Format code
just format

# Run all CI checks
just ci

Building

# Build binary
just build

# Clean build artifacts
just clean

Release Process

1. Bump version:

   just release patch  # or minor, major
   

2. Push changes and tags:

   git push && git push --tags
   

3. GitHub Actions automatically:

   • Builds binaries for multiple platforms
   • Creates GitHub Release with assets

License

MIT - see LICENSE file for details.

Contributing

Contributions welcome! Please open an issue or pull request.