iterative-works/iw-cli

Watch

Fork 0

Agent-usable CLI: projects, worktrees, status commands + Claude-in-tmux #222

New issue

Closed

opened 2026-02-24 13:39:09 +00:00 by mprihoda · 1 comment

mprihoda commented

2026-02-24 13:39:09 +00:00

(Migrated from github.com)

Problem

A personal assistant agent needs to use iw exclusively to manage development workflows. Currently iw lacks the primitives the agent needs: listing projects, listing worktrees with status, getting detailed worktree state, and launching an agent in a worktree session.

Additionally, several commands violate the architecture rule of not importing from dashboard/ — ServerClient, ServerConfigRepository, and ProcessManager are pure I/O adapters that happen to live in dashboard/.

Goal

Add CLI commands and enhancements so an agent can:

Discover projects and worktrees
Get comprehensive status (git, PR, issue, review-state, progress)
Start work on an issue with an agent prompt
Send instructions to running sessions

All commands support --json for machine-readable output.

New commands

`iw projects [--json]`

List all known projects derived from registered worktrees in state.json.

Output: project name, main tree path, tracker type, team, worktree count.

`iw worktrees [--json]`

List worktrees for the current project with status summary from cached state.

Output per worktree: issue ID, path, PR state, review-state display, needs_attention flag.

`iw status [issue-id] [--json]`

Detailed status of one worktree combining cached + fresh local data.

Output: git (branch, clean/dirty), issue (title, status, url), PR (url, state, number), review-state (display, badges, artifacts, available_actions, needs_attention), progress (current phase, total phases).

Fresh review-state.json is read from disk; other data comes from server state cache.

Enhancements

`iw start <issue> --prompt "..."`

After worktree + tmux session creation, launch an agent in the pane with the given prompt.

--prompt implies detach — the command creates the session, sends the agent command via tmux send-keys, and exits immediately (no blocking tmux attach).

iw owns the agent launch mechanism. The caller provides the prompt (what to do), iw decides how to spawn the agent (currently: claude --dangerously-skip-permissions --prompt "..."). This allows changing the agent mechanism later without affecting callers.

`iw open <issue> --prompt "..."`

Send agent command to an existing worktree session. Same principle as start.

Architecture cleanup

Move shared infrastructure out of dashboard/ into proper layers:

Move to adapters/ (pure I/O, zero dashboard dependencies):

ServerClient — HTTP client for server communication
ServerConfigRepository — JSON config file I/O
ProcessManager — background process spawning and PID management

Move to model/ (pure logic):

MainProject.deriveMainProjectPath() → ProjectPath pure string logic

Extract to model/:

ServerStateCodec — shared ReadWriter instances for state JSON serialization

New in adapters/:

StateReader — reads state.json from standard location
TmuxAdapter.sendKeys() — send keystrokes to tmux session

After this, commands import only from model/ and adapters/. Dashboard imports from all three. Clean layering.

Implementation phases

Phase 1: Architecture cleanup

Move ServerClient, ServerConfigRepository, ProcessManager to adapters/
Extract ServerStateCodec to model/
Create StateReader adapter
Move deriveMainProjectPath to model/
Add TmuxAdapter.sendKeys
Update all imports

Phase 2: `iw projects` command

New command using StateReader + project derivation + config loading
--json flag support + E2E tests

Phase 3: `iw worktrees` command

Filters state by current project
Enriches with cached PR/review-state data
--json flag support + E2E tests

Phase 4: `iw status` command

Combines state.json caches + fresh review-state.json from disk
Resolves issue ID from arg or current branch
--json flag support + E2E tests

Phase 5: `--prompt` for start/open

Parse --prompt from args (implies --detach)
Wire TmuxAdapter.sendKeys after session creation
Skip tmux attach when --prompt given
E2E tests

## Problem A personal assistant agent needs to use `iw` exclusively to manage development workflows. Currently `iw` lacks the primitives the agent needs: listing projects, listing worktrees with status, getting detailed worktree state, and launching an agent in a worktree session. Additionally, several commands violate the architecture rule of not importing from `dashboard/` — `ServerClient`, `ServerConfigRepository`, and `ProcessManager` are pure I/O adapters that happen to live in `dashboard/`. ## Goal Add CLI commands and enhancements so an agent can: 1. Discover projects and worktrees 2. Get comprehensive status (git, PR, issue, review-state, progress) 3. Start work on an issue with an agent prompt 4. Send instructions to running sessions All commands support `--json` for machine-readable output. ## New commands ### `iw projects [--json]` List all known projects derived from registered worktrees in `state.json`. Output: project name, main tree path, tracker type, team, worktree count. ### `iw worktrees [--json]` List worktrees for the current project with status summary from cached state. Output per worktree: issue ID, path, PR state, review-state display, needs_attention flag. ### `iw status [issue-id] [--json]` Detailed status of one worktree combining cached + fresh local data. Output: git (branch, clean/dirty), issue (title, status, url), PR (url, state, number), review-state (display, badges, artifacts, available_actions, needs_attention), progress (current phase, total phases). Fresh review-state.json is read from disk; other data comes from server state cache. ## Enhancements ### `iw start <issue> --prompt "..."` After worktree + tmux session creation, launch an agent in the pane with the given prompt. `--prompt` implies detach — the command creates the session, sends the agent command via `tmux send-keys`, and exits immediately (no blocking `tmux attach`). **iw owns the agent launch mechanism.** The caller provides the prompt (what to do), iw decides how to spawn the agent (currently: `claude --dangerously-skip-permissions --prompt "..."`). This allows changing the agent mechanism later without affecting callers. ### `iw open <issue> --prompt "..."` Send agent command to an existing worktree session. Same principle as start. ## Architecture cleanup Move shared infrastructure out of `dashboard/` into proper layers: **Move to `adapters/`** (pure I/O, zero dashboard dependencies): - `ServerClient` — HTTP client for server communication - `ServerConfigRepository` — JSON config file I/O - `ProcessManager` — background process spawning and PID management **Move to `model/`** (pure logic): - `MainProject.deriveMainProjectPath()` → `ProjectPath` pure string logic **Extract to `model/`**: - `ServerStateCodec` — shared ReadWriter instances for state JSON serialization **New in `adapters/`**: - `StateReader` — reads state.json from standard location - `TmuxAdapter.sendKeys()` — send keystrokes to tmux session After this, commands import only from `model/` and `adapters/`. Dashboard imports from all three. Clean layering. ## Implementation phases ### Phase 1: Architecture cleanup - Move `ServerClient`, `ServerConfigRepository`, `ProcessManager` to `adapters/` - Extract `ServerStateCodec` to `model/` - Create `StateReader` adapter - Move `deriveMainProjectPath` to `model/` - Add `TmuxAdapter.sendKeys` - Update all imports ### Phase 2: `iw projects` command - New command using StateReader + project derivation + config loading - `--json` flag support + E2E tests ### Phase 3: `iw worktrees` command - Filters state by current project - Enriches with cached PR/review-state data - `--json` flag support + E2E tests ### Phase 4: `iw status` command - Combines state.json caches + fresh review-state.json from disk - Resolves issue ID from arg or current branch - `--json` flag support + E2E tests ### Phase 5: `--prompt` for start/open - Parse `--prompt` from args (implies `--detach`) - Wire `TmuxAdapter.sendKeys` after session creation - Skip `tmux attach` when `--prompt` given - E2E tests

mprihoda commented

2026-03-14 10:51:26 +00:00

(Migrated from github.com)

Closed by b0d2152 IW-222: Agent-usable CLI — projects, worktrees, status + --prompt (#229)

Closed by b0d2152 IW-222: Agent-usable CLI — projects, worktrees, status + --prompt (#229)