Metadata-Version: 2.4
Name: mng-kanpan
Version: 0.1.2
Summary: All-seeing agent tracker
Requires-Python: >=3.11
Requires-Dist: click-option-group>=0.5.6
Requires-Dist: click>=8.0
Requires-Dist: mng==0.1.7
Description-Content-Type: text/markdown

# Kanpan

All-seeing agent tracker. The name combines Sino-Japanese 看 (*kan*, "to look", as in 看板 *kanban*) and Greek πᾶν (*pan*, "all") -- a unified view that aggregates state from all sources (mng agent lifecycle, git branches, GitHub PRs and CI) into a single board.

Launch with `mng kanpan`. Requires the `gh` CLI to be installed and authenticated.

## Filtering

Filter which agents appear on the board using CEL expressions:

```bash
# Show only agents for a specific project
mng kanpan --project mng

# Show only running agents
mng kanpan --include 'state == "RUNNING"'

# Exclude done agents
mng kanpan --exclude 'state == "DONE"'
```

`--include` and `--exclude` accept arbitrary CEL expressions (repeatable). `--project` is a convenience shorthand that translates to an include filter on `labels.project`. Multiple `--project` flags are OR'd together.

When any filter is active, the header displays a `[filtered]` indicator.

## Custom commands

Add to your mng settings file (e.g. `.mng/settings.toml`):

```toml
[plugins.kanpan.commands.c]
name = "connect"
command = "mng connect $MNG_AGENT_NAME"

[plugins.kanpan.commands.l]
name = "events"
command = "mng events $MNG_AGENT_NAME"
refresh_afterwards = true
```

Each entry defines a keybinding (the table key, e.g. `c`) that appears in the status bar and runs with the `MNG_AGENT_NAME` environment variable set to the focused agent's name. Custom commands override builtins when they share the same key. Set `enabled = false` to disable a builtin.

By default, custom commands run immediately on the focused agent. Set `markable = true` to make a command use dired-style batch marking instead: pressing the key marks agents, then `x` executes all marks at once.

```toml
[plugins.kanpan.commands.s]
name = "stop"
command = "mng stop $MNG_AGENT_NAME"
markable = true
refresh_afterwards = true
```

## Refresh behavior

Kanpan uses two refresh strategies:

- **Full refresh** (manual 'r' key, periodic 10-minute timer): fetches both agent state and GitHub PR data. Only one can be in flight at a time -- pressing 'r' while a refresh is running is ignored.
- **Agent-only refresh** (after push, delete, custom commands): fetches agent state without hitting the GitHub API. PR data is carried forward from the previous snapshot.

Both are configurable:

```toml
[plugins.kanpan]
# Seconds between periodic full refreshes (default 10 minutes)
refresh_interval_seconds = 600.0
# Seconds before retrying after a failed full refresh
retry_cooldown_seconds = 60.0
```

## Refresh hooks

Run shell commands before and/or after each full refresh. Each hook runs once per agent, in parallel across all agents. Hook failures are reported as board errors but do not block the refresh.

```toml
[plugins.kanpan.on_before_refresh.notify]
name = "Pre-refresh notify"
command = "echo Refreshing $MNG_AGENT_NAME"

[plugins.kanpan.on_after_refresh.sync]
name = "Post-refresh sync"
command = "my-sync-script"
```

Before-hooks run against the previous snapshot's entries (skipped on the first refresh). After-hooks run against the new snapshot's entries. Set `enabled = false` to disable a hook without removing it.

Each hook command receives the following environment variables:

| Variable | Description |
|---|---|
| `MNG_AGENT_NAME` | Agent name |
| `MNG_AGENT_BRANCH` | Git branch (empty if none) |
| `MNG_AGENT_STATE` | Agent lifecycle state (e.g. `RUNNING`, `DONE`) |
| `MNG_AGENT_PROVIDER` | Provider instance name |
| `MNG_AGENT_PR_NUMBER` | PR number (empty if no PR) |
| `MNG_AGENT_PR_URL` | PR URL (empty if no PR) |
| `MNG_AGENT_PR_STATE` | PR state such as `OPEN`, `MERGED`, `CLOSED` (empty if no PR) |
