custcli

custcli is a local orchestration CLI for paired coding workflows.

• gemini handles planning and review
• opencode handles execution and live editing
• custcli coordinates both and stores local artifacts under .custcli/

Trust Model

custcli does not run its own OAuth flow.

• it does not host a third-party login page
• it does not proxy Gemini credentials through a custcli service
• it uses the Gemini CLI and OpenCode CLI that are already installed on your machine
• authentication stays with those tools

If gemini works in your terminal, custcli reuses that local setup.

Install

Requirements:

• Node.js 20 or newer
• Gemini CLI installed and already authenticated
• OpenCode CLI installed and available on PATH

From a local checkout:

npm install -g .

From GitHub:

npm install -g git+https://github.com/NVSRahul/custcli.git

After install:

custcli --help

Quick Start

Plan only:

custcli plan --cwd "/path/to/project" "review this codebase and produce a plan"

Plan and execute:

custcli run --cwd "/path/to/project" "implement the requested change"

Live TUI:

custcli live --new-session --planner-model auto

Strict live TUI:

custcli live --new-session --planner-model auto --planner-mode strict

Use strict only if you want Gemini enforced first on substantive turns. It is more structured, but it can use more context and call Gemini more often than the default free mode.

List live sessions:

custcli sessions

Prune old heavy artifacts:

custcli prune --keep-last 20

Screenshots

• Gemini running state
• Gemini completed state

Platform Notes

custcli is written in Node.js and uses direct process spawning plus Node path handling. It is designed to work on macOS, Linux, and Windows.

Practical notes:

• on Windows, use PowerShell or Windows Terminal
• make sure both gemini and opencode are installed and callable from the same shell
• the live TUI requires a normal interactive terminal

Documentation

The full manual is in HELP.md.

License: MIT