DOCSEARCHbyAlgolia
Submit Docs

ccmanager

repository·main·Indexed 22 days ago

https://github.com/kbwo/ccmanager

A TUI application for managing multiple AI coding assistant sessions, such as Claude Code and Gemini CLI, across different Git worktrees. It features real-time session monitoring, context preservation between branches, multi-project discovery, and automation hooks for status changes and worktree creation. It also includes an experimental Auto Approval feature to automate session progression using custom commands or the Claude CLI.

Tokens
18.9K
Snippets
58
Records
89
Agent score
79%

What's inside ccmanager

  1. Understand CCManager's Enhanced Worktree Status Indicators

    main

    When extensions.worktreeConfig is enabled, CCManager displays a detailed status bar for each worktree using the following format:

    <branch-name> [<ahead-behind> <parent>] <file-changes>

    Visual Indicators

    • Ahead/Behind: ↑ (Green) indicates commits ahead of parent; ↓ (Red) indicates commits behind parent.
    • Parent Branch: Shown in dim text (e.g., main).
    • File Changes: Shows additions and deletions (e.g., +25 -10).

    Examples

    • feature/auth [↑5 ↓2 develop] +120 -45 (Feature branch ahead of and behind develop)
    • hotfix/security [↑1 main] +15 -3 (Hotfix with 1 commit ahead of main)
    • experiment/ai [↓10 main] +200 -50 (Experimental branch 10 commits behind main)

  2. How Auto Approval works

    main

    When a session enters a prompt state that normally waits for user input, the following lifecycle occurs:

    1. Detection: CCManager marks the session as Auto-approval pending... and captures up to 300 lines of recent terminal output.
    2. Evaluation:
      • Default: CCManager runs claude --model haiku -p --output-format json --json-schema ... using the captured output.
      • Custom: CCManager runs your customCommand.
    3. Decision:
      • If the evaluator determines permission is not needed, CCManager sends a carriage return (\r) to the session (simulating the Enter key).
      • If permission is needed, or if the evaluator times out (60s), errors, or you press any key during the pending state, the process stops and reverts to manual approval.

    Limitations & Safety

    • Input Type: Auto-approval only sends \r (Enter). It cannot handle prompts requiring specific typed text.
    • Safety First: If the helper command fails for any reason, CCManager defaults to requiring manual approval.

  3. Configure per-project settings with .ccmanager.json

    main
    CCManager supports project-specific configurations. Place a .ccmanager.json file in your git repository root. These settings are merged with the global configuration found at ~/.config/ccmanager/config.json, with the project-level settings taking priority.

  4. Automate workflows with Status Change Hooks

    main
    CCManager can execute custom commands whenever a session's state changes (e.g., moving from Busy to Waiting). This is useful for triggering desktop notifications or logging activity.

  5. Understand limitations of per-project configuration

    main
    Per-project configuration is not available when CCManager is running in multi-project mode. If you use the --multi-project flag during startup, CCManager will ignore any .ccmanager.json files and only use the global configuration.

  6. How session management works in Multi-Project Mode

    main

    CCManager maintains separate session managers for each project. This allows you to work across different projects simultaneously without losing progress.

    • Persistence: Sessions persist when you switch between projects.
    • Background Execution: Sessions continue running in the background even when you navigate away from a project to another one in the list.
    • Monitoring: Each project tracks its own active, busy, and waiting sessions, displayed as [active/busy/waiting] in the menu.

  7. Use Effect vs Either in CCManager

    main

    When writing new code for CCManager, choose between Effect and Either based on the nature of the operation:

    • Use Effect for asynchronous operations or operations with side effects (e.g., Git commands, file I/O, PTY spawning). These return Effect.Effect<T, E, never>.
    • Use Either for synchronous, pure operations (e.g., configuration validation, path resolution). These return Either.Either<E, T>.

  8. Automate environment setup with Worktree Hooks

    main

    Worktree hooks allow you to run commands automatically after a new worktree is created.

    Available Environment Variables:

    • Worktree path
    • Branch name
    • Git root

    These hooks run asynchronously and do not block the worktree creation process.

  9. Compose and recover from errors with Effect

    main

    Effect allows for powerful composition and recovery patterns:

    Parallel Queries: Use Effect.all to run multiple effects concurrently.

    Sequential Composition: Use Effect.flatMap to chain operations where the second depends on the first.

    Error Recovery:

    • Use Effect.catchTag to recover from a specific error type (e.g., GitError).
    • Use Effect.catchAll to provide a fallback value for any error.
    // Parallel
const loadBranchData = Effect.all([
  worktreeService.getAllBranchesEffect(),
  worktreeService.getDefaultBranchEffect()
], { concurrency: 2 });

// Recovery by Tag
const withRecovery = Effect.catchTag(
  createWorktreeEffect(path, branch),
  'GitError',
  (error) => {
    if (error.exitCode === 128) return createWorktreeEffect(path + '-2', branch + '-2');
    return Effect.fail(error);
  }
);

// Fallback
const worktreesWithFallback = Effect.catchAll(
  worktreeService.getWorktreesEffect(),
  (error) => Effect.succeed([defaultWorktree])
);

  10. How Devcontainer Integration Works

    main

    CCManager manages the lifecycle of the containerized session through a specific sequence:

    1. Container Startup: When a worktree is selected, CCManager executes the command provided in --devc-up-command to ensure the environment is running.
    2. Session Creation: The AI assistant command is executed inside the container using the command provided in --devc-exec-command.
    3. Command Construction: CCManager automatically appends your preset command and its arguments after a -- separator. For example, if your exec command is devcontainer exec --workspace-folder ., CCManager will construct: devcontainer exec --workspace-folder . -- <your-preset-command>.
    4. Host Management: CCManager stays on the host machine to manage the PTY session and trigger status hooks (like desktop notifications).

  11. Enable Multi-Project Mode

    main

    Multi-project mode allows you to manage multiple git repositories from a single interface. To use this mode, you must set the CCMANAGER_MULTI_PROJECT_ROOT environment variable to a directory containing your git repositories. CCManager will recursively scan this directory for all git projects.

    To run CCManager in this mode, use the --multi-project flag.

    Note: If the environment variable is not set, CCManager will display an error message and fail to start in multi-project mode.

    # 1. Set the root directory containing your git repos
export CCMANAGER_MULTI_PROJECT_ROOT="/path/to/your/projects"

# 2. Run CCManager in multi-project mode
npx ccmanager --multi-project

  12. Enable Auto Approval (Experimental)

    main

    Auto Approval allows CCManager to automatically decide if a paused Claude Code session can continue without manual user input (pressing Enter).

    Note: This feature is experimental. It requires the claude CLI to be installed and available on your PATH. If you do not have claude installed, you must provide a customCommand.

    Via the UI

    1. Run ccmanager.
    2. Navigate to Global Configuration → Other & Experimental.
    3. Toggle Auto Approval (experimental) to ✅ Enabled.
    4. (Optional) Use Edit Custom Command to specify a custom approver script.
    5. Select Save Changes.

    Via Configuration File

    Edit the config.json file directly:

    • Linux/macOS: ~/.config/ccmanager/config.json
    • Windows: %APPDATA%\ccmanager\config.json
    {
  "autoApproval": {
    "enabled": true
  }
}