Metadata-Version: 2.4
Name: navig-agentctl
Version: 0.2.0
Summary: Agent Control Center (devops section): sessions, worktrees & tasks — one read-only view, then a controller.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,orchestration,plugin,devops,worktrees,sessions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: navig>=0.1.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# navig-agentctl

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Agent Control Center (devops section): sessions, worktrees & tasks — one read-only view, then a controller.

**A navig extension** — installing it pulls in navig and adds the commands below · v0.2.0 · not on PyPI yet (install from source below)

**Install**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-agentctl"
navig agentctl --help
```

It is not a separate program: it needs navig, and installing it installs navig for you.

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig agentctl sessions` | Live agent sessions (who is working where, idle or active). |
| `navig agentctl status` | One-line overview: sessions, worktrees (cwd repo), tasks. |
| `navig agentctl tasks` | Unified tasks from the board and the work queue. |
| `navig agentctl worktrees` | Git worktrees of a repo: branch, ahead/behind, dirty, last commit. |

</details>

<!-- navig:plugin-card:end -->

**Agent Control Center** — the devops section for managing AI coding agents across
sessions, git worktrees and task records. Local-first, provider-agnostic, read-only
in Phase 1.

## Phases

| Phase | Name | What it does |
|---|---|---|
| 1 | Observer | Discover live agent sessions · list worktrees + conflict radar · unified task read-model (board + work queue). **Changes nothing.** |
| **2a (this)** | Heartbeat | `POST /api/deck/agents/heartbeat` — the extension annotates workspace/editor/roster context; daemon-owned `state`/`pid`/`reason` are never written. |
| 2b | Controller | Launch CLI agents into worktrees, assign task specs, pause/terminate owned processes, collect handoff reports, detect ownership conflicts. |
| 3 | Orchestrator | Schedule by dependency, allocate by capacity, trigger reviews, recover interrupted work — production deploys always ask a human first. |

## CLI

```
navig agentctl sessions [--project P] [--json]
navig agentctl worktrees [--project PATH] [--conflicts] [--json]
navig agentctl tasks [--source board|work] [--json]
navig agentctl status [--json]
```

## Deck routes (the contract)

All under `/api/deck/agents`, gated on the `agentctl` module. GET-only in Phase 1:

- `GET /api/deck/agents/sessions` — live sessions (from `navig procs` semantics) merged with the persistent registry.
- `GET /api/deck/agents/worktrees?project=&conflicts=` — worktrees + pairwise conflict radar.
- `GET /api/deck/agents/tasks` — board cards + work items, one normalised shape.

The OS app (Control Center tile) and navig-dev (VS Code tree views) are both
consumers of this one contract.

## Store

`~/.navig/data/store/agentctl.db` — session ledger (who was active where, with
state-change history) and task bindings (which session owns which task). Task
truth stays in `board.db` / `work.db`; this ledger only answers ownership.

## Non-negotiables

Local-first · provider-agnostic adapters · explicit process ownership · safe git
handling · no duplicate task execution · **no automatic merge or deployment**.
