pi-tmux-task AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-05-20
Updated: 2026-05-22

OVERVIEW

Project: pi-tmux-task

This repository is a Pi extension package for Pi-session-scoped background task management. It does not implement its own scheduler. Instead, it defines an agent-facing background-task convention and backs that convention with tmux plus extension-side observability.

Core product idea

1. Skill guidance for background task management

   • Bundle a skill that teaches the agent when to treat work as a long-running background task instead of a foreground command.
   • Standardize on one Pi session = one task tmux session and one logical task = one tmux window / task slot.
   • Encourage meaningful task naming, reuse of the same task slot on rerun when possible, and follow-up by window_id when precise low-level targeting is useful.

2. Code-level runtime support

   • Compute a stable Pi-session-scoped tmux session name and inject it into bash calls as PI_TMUX_SESSION.
   • Provide UI surfaces to inspect and manage tmux task windows.
   • Poll tmux state, diff snapshots into semantic task events, and push plain-text notifications back into the active Pi conversation.

Current stack

• Language: TypeScript + ESM
• Runtime: Node.js
• Host framework: @earendil-works/pi-coding-agent
• UI: @earendil-works/pi-tui
• Shell integration: tmux + bash helper scripts
• Tests: lightweight Node/bash scripts under test/

STRUCTURE

.
├── AGENTS.md
├── docs/
│   ├── architecture.md
│   └── tmux-task-event-flow.md
├── package.json
├── skills/
│   └── tmux-task-manager/
│       ├── SKILL.md
│       └── tmux-task-run.sh
├── src/
│   ├── context.ts
│   ├── index.ts
│   ├── types.ts
│   ├── tmux/
│   │   ├── commands.ts
│   │   ├── events.ts
│   │   ├── parse.ts
│   │   ├── poller.ts
│   │   └── snapshot.ts
│   └── ui/
│       └── tasks-panel.ts
└── test/
    ├── context.mjs
    ├── events.mjs
    └── tmux-integration.sh