https://github.com/glav/copilot-cli-terminal
A test project to use copilot cli with a dedicated multi-agent terminal
https://github.com/glav/copilot-cli-terminal
Last synced: about 1 month ago
JSON representation
A test project to use copilot cli with a dedicated multi-agent terminal
- Host: GitHub
- URL: https://github.com/glav/copilot-cli-terminal
- Owner: glav
- Created: 2026-01-14T23:25:25.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-20T05:27:17.000Z (4 months ago)
- Last Synced: 2026-01-20T05:50:28.085Z (4 months ago)
- Language: Python
- Size: 846 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Copilot multi-persona CLI
This repository provides a multi-persona terminal workflow for GitHub Copilot CLI using `tmux`.
## Quick start
```bash
uv run copilot-multi start
```
## Copilot multi-persona CLI (MVP)
This repo includes an MVP terminal tool that launches a 4-persona workflow using `tmux` panes (Linux-only).
This tool orchestrates panes and shared context files; it does not replace the underlying GitHub Copilot CLI.
### Prereqs
- `tmux` installed and available on `PATH`
- GitHub Copilot CLI (`copilot`) installed and authenticated
Debian/Ubuntu (including many devcontainers):
```bash
sudo apt-get update
sudo apt-get install -y tmux
```
### Install GitHub Copilot CLI
GitHub Copilot CLI is currently distributed via multiple methods (choose one):
- WinGet (Windows)
- Homebrew (macOS and Linux)
- npm (all platforms, requires Node.js 22+)
- Install script (macOS and Linux)
### Authenticate
On first launch of `copilot`, you’ll be prompted to log in using the `/login` slash command.
For non-interactive/auth automation, you can also use a fine-grained PAT with the “Copilot Requests” permission via `GH_TOKEN` or `GITHUB_TOKEN`.
When you run `copilot-multi start`, it will preflight-check whether `copilot` is already authenticated. If not, it will temporarily launch `copilot` so you can run `/login`, then it continues and starts the tmux session.
Note: the first time it launches `copilot` you may also see a folder trust prompt. Choose “Yes, and remember this folder for future sessions” if you want to avoid being asked again.
### Run
```bash
uv run copilot-multi start
```
### Pane scrollback (no per-pane scrollbars)
tmux panes do **not** support visible vertical scrollbars.
What you *can* do is scroll each pane’s own history buffer:
- Mouse wheel: when mouse mode is enabled (default), scroll the wheel over a pane to enter tmux copy-mode and scroll that pane’s history.
- Keyboard: `Ctrl+b` then `[` to enter copy-mode, then use arrow keys / PageUp / PageDown. Press `q` to exit.
This project sets a higher tmux `history-limit` by default so you’re less likely to lose output.
If you want “never lose output”, enable logging:
```bash
uv run copilot-multi start --log-dir .copilot-multi/logs
```
This writes one file per pane (e.g. `pm.log`, `impl.log`, `review.log`, `docs.log`).
To start the session in the background (no attach):
```bash
uv run copilot-multi start --detach
```
This creates/uses `.copilot-multi/` for shared context and a session state file at `.copilot-multi/session.json`.
### What is `.copilot-multi/` and can I delete it?
`copilot-multi` keeps repo-local *runtime* files in `.copilot-multi/` (and it is gitignored).
Typical contents include:
- Shared working docs for the personas (e.g. `WORK_CONTEXT.md`, `DECISIONS.md`, `HANDOFF.md`)
- Coordination state for the running session (e.g. `session.json` plus a lock file)
- Troubleshooting artifacts (e.g. `logs/`, `history/`, `responses/`, `broker.log`)
- Local Copilot integration/cache files for the current machine
It is safe to clean when you are **not** running an active session:
- Clean everything (will be recreated on next start):
```bash
rm -rf .copilot-multi
```
- Or only clean logs/history:
```bash
rm -rf .copilot-multi/logs .copilot-multi/history .copilot-multi/responses
```
If you currently have a tmux session running, stop it first:
```bash
uv run copilot-multi stop
```
Each tmux pane starts in a lightweight "Copilot router" REPL:
- Anything you type is forwarded to the GitHub Copilot CLI (`copilot`) via a shared local broker, so all panes share one Copilot session/history.
- To run wrapper commands locally (not via Copilot), prefix them with `copilot-multi`, for example: `copilot-multi status`.
- Include another pane's latest response inline with `{{ctx:}}` (or legacy `{{last:}}`), where `` is `pm`, `impl`, `review`, or `docs`.
- Request another persona inline with `{{agent:}}` or `{{agent.}}` (runs `copilot-multi ask --prompt ...` sequentially; mirrors the prompt in that persona pane; uses the text *after* the marker up to the next marker/end; respects `--timeout`/`--poll`). The originating pane receives only the text before the first agent marker.
Example:
```text
Tell me a dad joke about unicorns. {{agent:review}} Review the joke from {{ctx:pm}}
```
The PM pane receives only the text before the first agent marker; the review pane receives the text after its marker.
If you want to authenticate Copilot CLI ahead of time (without launching tmux):
```bash
uv run copilot-multi auth
```
### Pane colors / theme
The pane REPL supports ANSI-colored headers and persona prompts (e.g. `pm>`, `review>`).
Config lookup (lowest → highest precedence):
- `~/.config/copilot-multi/config.toml` (or `$XDG_CONFIG_HOME/copilot-multi/config.toml`)
- `./copilot-multi.toml`
- `./.copilot-multi/config.toml`
- `$COPILOT_MULTI_CONFIG` (explicit path)
Example `copilot-multi.toml`:
```toml
[ui]
color = true
[ui.styles]
header = "bold cyan"
tips = "dim"
prompt_delim = "dim white"
input = "bright_black"
[ui.persona_prompt]
pm = "bold magenta"
impl = "bold blue"
review = "bold green"
docs = "bold yellow"
```
### Coordination
```bash
uv run copilot-multi status
uv run copilot-multi set-status pm working --message "Drafting scope + acceptance"
uv run copilot-multi wait impl --status done --timeout 1800
uv run copilot-multi stop
```
## Linting and formatting
This repo includes `ruff`.
```bash
uv sync --group dev
uv run ruff check .
uv run ruff format .
```
## Environment variables
- Copy `.env-sample` to `.env` and fill in values as needed.
- `.env` is gitignored.
```bash
cp .env-sample .env
```
## Copilot / AI Assisted workflow
This repo includes an `.agent/` directory containing reusable prompt “commands” and standards you can use with GitHub Copilot (and other coding agents).
- `.agent/commands/`: ready-to-run prompts for common tasks, for example:
- `setup/`: repo bootstrap tasks (e.g. creating `AGENTS.md`)
- `project/`: planning prompts (e.g. sprint planning)
- `docs/`: documentation prompts (e.g. creating ADRs)
- `.agent/standards/`: standards for consistent artifacts (ADRs, feature specs, task plans)
- `.agent/instructions/`: “apply-to” instructions that guide how agents write certain file types (e.g. Bash and Bicep)
Treat `.agent/` as a starting library: keep what helps your team, remove what doesn’t, and add org-specific workflows over time.