Local Agent Workbench

Japanese readers: start with README.ja.md or the full Japanese documentation hub.

A macOS/tmux workbench for running multiple local AI-agent CLI sessions in one window.

The first supported target is Codex CLI. The goal is simple: open 4, 6, or 9 agent panes against one shared workspace so you can collect ideas, compare approaches, run parallel research, and keep the resulting files in one place.

Use It When

Use Local Agent Workbench when one AI chat is too small for the job.

• You want 4, 6, or 9 Codex CLI sessions looking at the same problem from different angles.
• You are researching a technical topic and want separate panes for sources, risks, examples, and synthesis.
• You are maintaining OSS and want structured notes for issue triage, PR review, release prep, or docs cleanup.
• You want reusable Markdown output instead of scattered chat replies.
• You want a local-first setup that is easy to inspect, validate, and share safely.

Beginner-Friendly Guides

New to this project? Start with a plain-language explanation:

• English beginner guide
• 日本語のやさしい解説
• Recipes: practical ways to use the workbench.
• Promotion kit: short copy for sharing the project.

Start Here

Choose the shortest path for your situation:

• Start Here / まずここから: understand the project in the first 3 minutes.
• Use Cases / ユースケース: pick a practical workflow such as issue triage, PR review, release prep, or feature discovery.

Install In 60 Seconds

curl -fsSL https://raw.githubusercontent.com/goonobu-dot/local-agent-workbench/main/scripts/install.sh | bash
cd "$HOME/AgentWorkbench/local-agent-workbench"
make first-run

Full setup notes are in docs/install.md.

Try Without Installing

git clone https://github.com/goonobu-dot/local-agent-workbench.git
cd local-agent-workbench
./scripts/doctor.sh
make demo

Demo Preview

The fastest no-risk preview is make first-run: it checks your machine, creates a temporary demo workflow, closes it into a handoff summary, and lists available workflow templates.

Read docs/demo-transcript.md to see the expected output shape before running anything locally.

If you are unsure where to start, run:

./scripts/recommend_workflow.sh issue
./scripts/recommend_workflow.sh security

Who This Is For

• OSS maintainers who need faster issue triage, pull request review, release preparation, or security screening.
• Developers who want several independent Codex CLI angles on one local folder without building a hosted system.
• Researchers and builders who want reusable markdown outputs instead of scattered chat transcripts.

What You Get In 5 Minutes

• a local 4, 6, or 9 pane tmux workbench
• workflow templates for issue triage, PR review, release prep, and feature discovery
• one shared folder containing role prompts, pane notes, and a final handoff summary
• a doctor report and quality gates so setup problems are easier to diagnose

Example Outputs

• issue triage result
• pull request review verdict
• release checklist
• feature decision memo
• security triage
• documentation improvement plan
• dependency update review

Share A Usage Report

If the workbench helps you make a real maintenance decision, open a usage report. Short reports are useful: the workflow used, what it produced, and where the setup was confusing.

Codex For Open Source

This project is maintained as a practical Codex-assisted OSS workflow experiment. The updated application notes are in docs/CODEX_FOR_OSS_REAPPLICATION.md.

For a fast external review, use:

• Reviewer quick check
• Recent improvements
• External research notes
• Codex for OSS reviewer walkthrough

Why This Exists

AI agents are useful, but one chat window is often too narrow for exploration. This workbench gives you a repeatable local setup for:

• parallel research and idea generation
• comparing multiple solution paths side by side
• keeping all panes pointed at the same project folder
• switching between 4, 6, and 9 panes without rebuilding your terminal layout
• launching the setup as a small macOS app shortcut

Requirements

• macOS
• tmux
• Codex CLI available on your PATH
• Python 3 and Pillow only if you regenerate the icon

Install tmux with Homebrew:

brew install tmux

Quick Start

One-command install:

curl -fsSL https://raw.githubusercontent.com/goonobu-dot/local-agent-workbench/main/scripts/install.sh | bash

Then launch:

cd "$HOME/AgentWorkbench/local-agent-workbench"
make demo
./scripts/launch_codex_tmux.sh

Check your local setup without starting a workbench session:

./scripts/doctor.sh

Run the local validation suite:

make test

Create a reusable maintainer workflow folder before launching panes:

./scripts/new_workflow.sh issue-triage
AGENT_WORKBENCH_IDEA_DIR="$HOME/AgentWorkbench/Idea" ./scripts/launch_codex_tmux.sh

Start directly from a public GitHub issue or pull request URL:

./scripts/create_workflow_from_url.sh https://github.com/owner/repo/issues/123
./scripts/create_workflow_from_url.sh https://github.com/owner/repo/pull/123

Launch with role-specific prompts generated from pane-roles.md:

AGENT_WORKBENCH_IDEA_DIR="$HOME/AgentWorkbench/Idea" \
AGENT_WORKBENCH_USE_ROLE_PROMPTS=1 \
./scripts/launch_codex_tmux.sh

After the panes write their notes, create a handoff summary:

./scripts/close_workflow.sh "$HOME/AgentWorkbench/Idea"

Check workflow status before sharing or closing:

./scripts/workflow_status.sh "$HOME/AgentWorkbench/Idea"

Export a workflow folder for sharing:

./scripts/export_workflow.sh "$HOME/AgentWorkbench/Idea"

Import a shared workflow archive:

./scripts/import_workflow.sh ./Idea-workflow-export.tar.gz

All panes use one shared idea folder by default:

~/AgentWorkbench/Idea

Manual clone instead of the installer:

mkdir -p "$HOME/AgentWorkbench"
git clone https://github.com/goonobu-dot/local-agent-workbench.git "$HOME/AgentWorkbench/local-agent-workbench"
cd "$HOME/AgentWorkbench/local-agent-workbench"
./scripts/doctor.sh

Controls

• control-b z: zoom or unzoom the active pane
• control-b 4: switch to 4 panes
• control-b 6: switch to 6 panes
• control-b 9: switch back to 9 panes

Configuration

The public configuration names are AGENT_WORKBENCH_*. Older CODEX_WORKBENCH_* names are still accepted as compatibility aliases.

AGENT_WORKBENCH_PANE_COUNT=4 ./scripts/launch_codex_tmux.sh
AGENT_WORKBENCH_BASE="$HOME/AgentWorkbench" ./scripts/launch_codex_tmux.sh
AGENT_WORKBENCH_IDEA_DIR="$HOME/AgentWorkbench/Research" ./scripts/launch_codex_tmux.sh
AGENT_WORKBENCH_MODEL="gpt-5.4-mini" ./scripts/launch_codex_tmux.sh
AGENT_WORKBENCH_AUTO_SUBMIT=0 ./scripts/launch_codex_tmux.sh

Defaults:

Setting	Default
AGENT_WORKBENCH_PANE_COUNT	9
AGENT_WORKBENCH_SESSION	local-agent-9
AGENT_WORKBENCH_BASE	~/AgentWorkbench
AGENT_WORKBENCH_IDEA_DIR	~/AgentWorkbench/Idea
AGENT_WORKBENCH_MODEL	gpt-5.4-mini
AGENT_WORKBENCH_AUTO_SUBMIT	1

Workflow Recipes

See docs/workflows.md for practical patterns:

• parallel research
• competing hypotheses
• feature discovery
• small task mode
• public-output safety checks

See also:

• docs/oss-maintainer-use-cases.md
• docs/showcase.md
• docs/why.md
• docs/one-minute-demo.md
• docs/evaluation-guide.md
• docs/install.md
• docs/demo-transcript.md
• docs/adoption-scorecard.md
• docs/continuous-improvement-loops.md
• docs/commands.md
• docs/architecture.md
• docs/quality-gates.md
• docs/workflow-templates.md
• docs/workflow-sharing.md
• docs/troubleshooting.md
• docs/faq.md
• SUPPORT.md
• docs/publication-checklist.md
• docs/openai-codex-for-oss.md
• docs/adoption-plan.md

Example:

• examples/issue-triage-demo
• examples/pr-review-demo
• examples/release-prep-demo
• examples/feature-discovery-demo
• examples/security-triage-demo
• examples/docs-improvement-demo
• examples/dependency-update-demo

Project operations:

• ROADMAP.md
• CHANGELOG.md
• SECURITY.md

If you try it on a real or fictional maintainer task, share the result with the usage report issue template. Reports about confusing setup steps are as useful as reports about successful workflows.

Build The macOS App

./scripts/build_codex_app.sh
open "$HOME/Applications/Local Agent Workbench.app"

The generated app opens Terminal and launches the tmux workbench. The checked-in AppleScript does not contain a personal path. By default, it expects this repository at:

~/AgentWorkbench/local-agent-workbench

Safety Notes

This repository intentionally does not include local logs, .env files, prompt histories, Obsidian vaults, or generated agent output.

Before publishing your own fork, run:

make test

Project Status

This is an early public release extracted from a real local workflow. The current implementation focuses on Codex CLI because that is the tested path. The naming is intentionally broader so future adapters can support other local agent CLIs without changing the project identity.