agentic-workflow

agentic-workflow

Plugin for spawning peer AI coding agents (codex, claude) in tmux sessions for either persistent dialogue or task hand-off. Compatible with both Claude Code and Codex (via their respective plugin systems).

What it does

Lets a running AI coding agent spawn a peer agent in a tmux session, exchange messages with it across multiple turns, and hand off real tasks (refactors, fixes, migrations) the peer executes in the shared working directory. Built around two intents:

• Consultation — get a second opinion or cross-model review. Peer reads, you decide.
• Task hand-off — delegate work. Peer executes in your CWD, reports back. Verify with git diff.

Prerequisites

• A supported host: Claude Code or Codex (recent version with plugin support)
• tmux (any 3.x, stock config — the plugin uses an isolated socket)
• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh
• The peer CLIs you plan to invoke: codex, claude
• bin/peer must be on $PATH (see PATH setup below)

Install

The repo ships its own plugin marketplace catalog (.claude-plugin/marketplace.json for Claude Code; the equivalent Codex entry is shown below) plus both .claude-plugin/plugin.json and .codex-plugin/plugin.json, so the same checkout works under either host.

Claude Code — install from GitHub (recommended)

In any Claude Code session:

/plugin marketplace add msadig/agentic-workflow
/plugin install agentic-workflow@agentic-workflow

Updates: when you push new commits, users refresh with /plugin marketplace update agentic-workflow (or let auto-update handle it; every commit is a new version because plugin.json does not pin one).

Claude Code — local development

Skip the marketplace round-trip and point Claude at this checkout directly:

# Per-session
claude --plugin-dir /path/to/agentic-workflow

# Or treat the local checkout as a marketplace
/plugin marketplace add /path/to/agentic-workflow
/plugin install agentic-workflow@agentic-workflow

Codex — install from GitHub

Codex installs plugins via a marketplace catalog at ~/.agents/plugins/marketplace.json (or $REPO_ROOT/.agents/plugins/marketplace.json). Add an entry pointing at the repo:

{
  "name": "agentic-workflow",
  "plugins": [
    {
      "name": "agentic-workflow",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/msadig/agentic-workflow.git",
        "path": ".",
        "ref": "main"
      },
      "policy": { "installation": "AVAILABLE" }
    }
  ]
}

Then enable it from Codex (or set enabled = true for the entry in ~/.codex/config.toml). Updates: re-launch Codex; it re-resolves the git ref.

Codex — local development

Same marketplace.json location, but use a local source instead:

{
  "name": "agentic-workflow",
  "plugins": [
    {
      "name": "agentic-workflow",
      "source": {
        "source": "local",
        "path": "/path/to/agentic-workflow"
      },
      "policy": { "installation": "AVAILABLE" }
    }
  ]
}

Local sources resolve from disk on each load, so edits in your checkout propagate without re-installing.

PATH setup (required for both hosts)

The plugin's tooling lives in bin/peer, and neither host auto-prepends plugin bin/ directories to $PATH. Add this once to your shell rc (~/.zshrc, ~/.bashrc, etc.):

export PATH="/path/to/agentic-workflow/bin:$PATH"

Verify with which peer. Without this, every skill in the plugin fails at the first peer invocation.

Usage

The model-invoked skill (peer-agents) teaches Claude when and how to spawn peers. To call directly:

ID=$(peer spawn codex)
REPLY=$(peer send "$ID" "READ-ONLY REVIEW. Audit src/auth.py for security issues.")
echo "$REPLY"
peer end "$ID"

For task hand-off:

ID=$(peer spawn codex)
peer send "$ID" "TASK: Rename UserService to AccountService across src/. Run pytest after."
git diff --stat   # verify what actually changed
peer end "$ID"

For parallel peers (different non-overlapping tasks):

WORKER=$(peer spawn codex)
REVIEWER=$(peer spawn claude)
peer send "$WORKER" "TASK: ..." &
peer send "$REVIEWER" "READ-ONLY: ..." &
wait
peer end "$WORKER"; peer end "$REVIEWER"

Two intents: consultation vs. task hand-off

The plugin supports both:

• Consultation: peer reads code, returns advice, you decide. Phrase with READ-ONLY REVIEW.
• Hand-off: peer executes a task in your CWD (writes files, runs commands), reports back. Phrase with TASK: + explicit constraints. Always verify with git diff.

Safety: peers run unattended