chase

chase is a reusable log/debug toolkit for coding agents across multiple projects.

What it standardizes

• Human UI: zellij panes (or any terminal panes)
• Raw logs: .logs/*.log
• Agent entrypoint: chase
• Snapshot for agents: .debug/latest.md

Install into a target project

Using npm registry package:

npx @starbeach/chase /path/to/target-project

or:

pnpm dlx @starbeach/chase /path/to/target-project

To run chase without ./, install globally once:

npm i -g @starbeach/chase

From this repository (local development):

./scripts/install.sh /path/to/target-project

or:

./bin/chase-install /path/to/target-project

If omitted, target defaults to current directory.

chase install starts a setup flow and asks whether to install the bundled skill into .agents/skills/.

Generated files in target project

• .chase/config.json
• .logs/
• .debug/

Configure per project

Edit .chase/config.json in each target project:

{
  "commands": {
    "web": "pnpm dev",
    "app": "pnpm --filter app dev",
    "compose": "docker compose up"
  }
}

You can also customize targets, log paths, regex, and bundle hints.

Daily usage

chase dev-up web
chase dev-up app
chase dev-up compose

chase errors
chase logs web 120
chase summary
chase debug-bundle

chase debug-bundle writes .debug/latest.md for agent-first troubleshooting.

Agent-first usage

Use structured output for automation:

chase describe --output json
chase errors --output json
chase logs web 120 --output json
chase summary --output json
chase debug-bundle --output json

Safety flag:

chase dev-up web --dry-run --output json

Codex Skill

This repository includes a reusable skill:

• skills/chase-log-debug/SKILL.md

Use this skill when an agent should follow a strict chase-first debug flow.

For non-interactive environments, set CHASE_INSTALL_SKILL=1 (install) or CHASE_INSTALL_SKILL=0 (skip).

Versioning and Release

This repository uses Changesets.

# add release note
npm run changeset

# bump package version from pending changesets
npm run version-packages

# publish to npm
npm run release

Agent operating rule (recommended)

Tell agents to use this order:

1. Read .debug/latest.md
2. Run chase errors
3. Run chase logs <target> <lines> as needed

Design notes

• Keep entrypoints stable (chase) across projects.
• Swap internals later (compose/k8s/cloud logs) without changing agent workflow.
• Keep project-specific behavior in .chase/config.json only.
• Keep runtime logic in global chase; do not vendor shared scripts into each project.