# @muelsyse/pi-statusline-trellis

> 本项目二开于 [`@feniix/pi-statusline`](https://www.npmjs.com/package/@feniix/pi-statusline)，在原状态栏能力基础上增加 Trellis runtime 当前任务展示。

A fixed status display for pi. It shows two lines by default and adds a Claude Code-style Trellis task line when a current task is active.

By default it renders in the footer in interactive/RPC mode and stays inert in non-UI modes (`-p`, JSON mode).
It is not injected into model context and is not sent as messages.
In UI-capable sessions, it also exposes a `/statusline` tool for explicit retrieval.

## Display

```text
[P1] Task title (in_progress) · Muelsyse · 1 task(s)
Model: ... | Thinking: ... | Ctx: ... | ⎇ ... | dirty: +... | ↑.../↓...
<repo> | cwd: ... | 𖠰 ... | Skill: ... | Act: ...
```

The Trellis task line is omitted when no active Trellis task can be resolved from project-local runtime session state or legacy task files.

## Included fields

- Trellis current task, developer, and active task count, using Claude Code's middle-dot separator style when available
- Model
- Thinking level
- Context usage percent
- Git branch
- Dirty file count
- Input/output token totals
- Repo name
- Current working directory
- Git worktree label
- Last explicitly invoked skill
- Live activity indicator

## Live updates

The footer now updates continuously during active work instead of only at the end of a turn.
This includes:

- after user input is submitted
- when the agent starts and each turn starts
- while assistant messages are streaming
- while tools are starting, streaming updates, and finishing
- when the agent returns control to the user

To avoid excessive redraws, streaming-triggered footer renders are throttled.

## Activity behavior

The activity segment summarizes what pi is doing right now.
Examples:

- `Act: queued`
- `Act: thinking`
- `Act: responding`
- `Act: bash`
- `Act: bash x2`
- `Act: idle`

## Trellis task behavior

When a Trellis current task is active, `pi-statusline` prepends a Claude Code-style task line with the developer and active task count appended on the right:

```text
[P1] Bootstrap Guidelines (in_progress) · Muelsyse · 1 task(s)
```

Task discovery walks up from the current working directory to find a project-local `.trellis/` directory. Current tasks are resolved from `.trellis/.runtime/sessions/` first: `TRELLIS_CONTEXT_ID` selects the matching session file when present. When no matching context task is available, pi-statusline prefers a single active `pi_process_*` session, then falls back to a single active runtime session. If runtime session state is missing or ambiguous, pi-statusline falls back to the legacy `.trellis/.current-task` file for older Trellis projects.

Active task count is computed from non-archived directories under `.trellis/tasks/` that contain `task.json`. pi-statusline intentionally does not fall back to `~/.trellis/.current-task`, so sessions outside a Trellis project do not display stale global tasks.

## Skill behavior

The skill segment tracks the latest explicit skill command seen in user input.
Examples:
- `/skill:release` -> `Skill: release`
- `/release` -> `Skill: release` if `release` is registered as a skill command in the current session

## Token behavior

Token totals are based on assistant usage in the session branch.
During active streaming, the extension also uses the latest live assistant usage when available so the token display can update before the turn fully finishes.

## Worktree behavior

- linked worktree -> branch-derived label for that worktree
- main worktree -> `𖠰 main`
- non-git repo -> `𖠰 no git`

## Palette configuration

`pi-statusline` uses a built-in `defaultPalette`, but you can override any subset of colors through pi's standard settings files.

Settings locations:

- global: `~/.pi/agent/settings.json`
- project: `.pi/settings.json`

Use the `pi-statusline` key for non-secret configuration:

```json
{
  "pi-statusline": {
    "palette": {
      "model": "#008787",
      "activity": "#5FAF00"
    }
  }
}
```

`pi-statusline` does not need secrets. As a general pi convention, keep `settings.json` for non-secret defaults; credentials belong in environment variables, OAuth/private auth files, or explicit custom config files used by extensions that support them.

Supported palette keys:

- `background`
- `model`
- `repo`
- `thinking`
- `skill`
- `context`
- `branch`
- `dirty`
- `token`
- `separators`
- `cwd`
- `worktree`
- `activity`

Behavior:

- project settings override global settings
- missing keys fall back to `defaultPalette`
- invalid color values are ignored
- colors must be 6-digit hex values like `#008787`

## Development

Run from the repo root:

```bash
npm run test
npm run typecheck
```

For quick manual testing from this repository:

```bash
pi -e ./extensions/index.ts
```

To use this fork as a Pi package source, add it to `~/.pi/agent/settings.json`:

```json
{
  "packages": [
    "npm:@muelsyse/pi-statusline-trellis"
  ]
}
```

For local source testing, use a package filter path without a leading `./`:

```json
{
  "packages": [
    {
      "source": "D:/github/pi-statusline-trellis",
      "extensions": ["extensions/index.ts"]
    }
  ]
}
```