# pi-clean-footer

Clean, minimal, and lightweight powerline-style footer extension for [pi](https://pi.dev).

Shows a compact split footer:

![pi-clean-footer example](https://ik.imagekit.io/tqjjsoud1y/example.webp)

## Features

- Smart short model names, plus thinking effort (`low`, `med`, `high`, `xhigh`)
- Current directory basename only
- Git branch + dirty file count, including untracked files
- Event-driven git refresh after file-changing tools and user bash commands
- Context usage as `used/max`
- Cumulative active-branch token totals: input, output, total, cache read, cache write
- Optional session cost display (`$x.xx`) using provider cost data; auto-hides for zero-cost models
- Adaptive width tiers for narrow terminals
- `/footer` toggle
- `/footer refresh` force refresh

## Install

From npm (recommended) | https://www.npmjs.com/package/@neilurk12/pi-clean-footer:

```bash
pi install @neilurk12/pi-clean-footer
```

For project-local install:

```bash
pi install -l @neilurk12/pi-clean-footer
```

Or from local checkout (development):

```bash
pi install /absolute/path/to/pi-clean-footer
```

## Usage

Toggle footer:

```text
/footer
```

Force git refresh:

```text
/footer refresh
```

Show active config paths and resolved config:

```text
/footer config
```

Reload config after editing JSON:

```text
/footer reload
```

## Configuration

Config is optional. Defaults match the built-in package behavior.

Load order:

1. Global: `~/.pi/agent/clean-footer.json`
2. Project: `.pi/clean-footer.json`

Project config overrides global config. Nested `modelAliases` and `colors` are merged.

Example:

```json
{
  "preset": "compact",
  "enabled": true,
  "showGit": true,
  "showTokens": true,
  "showCacheRead": true,
  "showCacheWrites": false,
  "showContext": true,
  "showDirectory": true,
  "showEffort": true,
  "showCost": true,
  "gitRefreshDebounceMs": 500,
  "separator": " | ",
  "layouts": [
    {
      "minWidth": 100,
      "left": ["model", "directory", "git", "toks"],
      "right": ["cost", "context", "tokensFull"]
    },
    {
      "minWidth": 80,
      "left": ["model", "directory", "git", "toks"],
      "right": ["cost", "context", "tokensNoCache"]
    },
    {
      "minWidth": 60,
      "left": ["model", "directory", "git", "toks"],
      "right": ["cost", "context", "tokensTotal"]
    },
    {
      "minWidth": 40,
      "left": ["model", "directory", "git"],
      "right": ["cost", "context"]
    },
    {
      "minWidth": 0,
      "left": ["model"],
      "right": ["context"]
    }
  ],
  "contextWarningPercent": 70,
  "contextDangerPercent": 85,
  "modelAliases": {
    "claude-sonnet-4-5-20250929": "sonnet-4.5",
    "gpt-5.5-codex": "gpt-5.5"
  },
  "colors": {
    "model": "accent",
    "directory": "dim",
    "git": "success",
    "gitDirty": "warning",
    "contextNormal": "success",
    "contextWarning": "warning",
    "contextDanger": "error",
    "tokens": "muted",
    "cost": "muted",
    "separator": "dim"
  }
}
```

Preset example:

```json
{
  "preset": "minimal",
  "showGit": true
}
```

Supported presets:

| Preset | Description |
|---|---|
| `default` | Built-in footer behavior. |
| `minimal` | Quiet model + context layout with git, directory, and tokens hidden. |
| `compact` | Model, git, context, and total tokens with cache noise hidden. |
| `dense` | Full information layout with cache read and write counts enabled. |
| `focus` | Model + context only for low-distraction sessions. |
| `muted` | Softer semantic colors while keeping default-style behavior. |

Preset values are applied before user config, so explicit settings override the preset. Unknown preset names are ignored with a `/footer config` warning and default behavior is used.

Supported layout segment IDs:

- `model` - model name plus thinking effort when `showEffort` is enabled
- `directory` - current directory basename
- `git` - git branch and dirty count
- `context` - context usage
- `tokensFull` - input, output, total, cache read, and cache write tokens
- `tokensNoCache` - input, output, and total tokens
- `tokensTotal` - total tokens only
- `toks` - tokens-per-second rate or activity indicator
- `cost` - cumulative session cost in `$x.xx` format

`layouts` are selected by the highest `minWidth` less than or equal to the terminal width. `showGit`, `showTokens`, `showContext`, `showDirectory`, and `showEffort` still act as global visibility controls. `showCache` is a deprecated global cache-token gate; use `showCacheRead` and `showCacheWrites` to hide cache read (`↯`) and write (`↥`) counts independently. Unknown or duplicate layout segments are omitted and reported by `/footer config`.

Malformed JSON keeps defaults/last loaded behavior and reports an error through `/footer config` or at startup.

## Package manifest

This package declares its extension through `package.json`:

```json
{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}
```

## Development

Type-check extension:

```bash
npx tsc --noEmit --skipLibCheck --moduleResolution Node16 --module Node16 --target ES2022 --types node src/index.ts
```

## Notes

Extensions run with full system permissions. Review code before installing any pi package.