Apex Companion Coding

Always-on Apex Companion Coding for pi / pi-mono.

Apex is a multi-agent companion layer that runs alongside the main agent, discusses the current task, reads relevant project files, reviews risky file mutations, and pushes the main agent toward stronger implementations.

Highlights

• session-scoped activation (/apex on, /apex off)
• Apex only runs when explicitly turned ON for the current session; when OFF, live Apex status/widget/footer-line/review/discussion output stays hidden
• initial discussion steps can be turned on/off in Apex settings
• two live output modes:
  • widget → visible, not in session, not in context
  • chat-context → visible and fully part of session/context
• project-aware prompts built from relevant repo files
• preflight review for edit / write
• interception of risky bash-based file mutations like redirections, tee, cp, mv, rm, touch, mkdir, ln, chmod, chown, git rm, git mv, git restore, git checkout --, install, truncate, dd, and in-place shell edits
• live review status bar enriched with severity and category catches
• repair window to break non-ending block chains when the main agent needs follow-up edits across related files
• apex_negotiate tool so the main agent can propose a scoped contract back to Apex after a block
• richer footer/status styling with color-coded severity/category pills and animated-looking status updates
• custom Apex footer that replaces the default footer with a more premium multi-line project/model/status view
• premium footer badges, mini progress bars, severity pills, category counters, smarter idle/active layouts, and adaptive narrow-terminal layouts
• configurable review strictness
• configurable blocking action by severity
• animated widget mode with one live row per companion

Install

From npm as a pi package

pi install npm:pi-apex-companion-coding

Project-local install:

pi install -l npm:pi-apex-companion-coding

Then reload pi if needed:

/reload

From a local checkout during development

pi install /absolute/path/to/apex-companion-coding

Or use the extension directory directly:

ln -sfn "$PWD/apex-companion-coding" ~/.pi/agent/extensions/apex-companion-coding
/reload

Commands

/apex
/apex on
/apex off
/apex stop
/apex add
/apex edit <n>
/apex remove <n>
/apex list
/apex settings

When you run /apex with no parameters, Apex Companion Coding now shows the current apex team information and opens a select menu with the main available actions.

If Initial discussion steps is turned OFF in settings, Apex will stop running the pre-turn brainstorming discussion while still keeping the rest of the session-scoped Apex features available, such as mutation review.

For blocked multi-file fixes, the main agent can call apex_negotiate to propose a scoped contract back to Apex and unblock coordinated follow-up changes.

/apex stop gracefully cancels the currently running Apex discussion or mutation review without changing your saved configuration. /apex off deactivates Apex for the rest of the session, immediately hides live Apex widget/status output, and prevents new discussion/review/negotiation work from running until you explicitly turn Apex back on.

Settings

Apex settings currently support:

• Initial discussion steps
• Output mode
• Widget verbose/debug mode
  • widget
  • chat-context
• Discussion rounds
• Project awareness
• Review edits/writes
• Review strictness
  • lenient
  • balanced
  • strict
• Blocking LOW
• Blocking MEDIUM
• Blocking HIGH
• Blocking CRITICAL
• Include context
• Debug
  • when enabled, Apex also appends internal runtime notes (for example, same-target review skips) to .apex/runtime-notes.log

Blocking model

Severity levels:

• LOW
• MEDIUM
• HIGH
• CRITICAL

Blocking actions per severity:

• none
• partial
• block

Semantics

• none → never block, only warn
• partial → block once for a given mutation fingerprint, then allow retry
• block → always block that mutation attempt

This avoids infinite loops while still giving Apex a real quality-control role.

Output modes

widget

Best when you want live visibility without context pollution.

• informational chatter is not written to session messages
• informational chatter is not part of context
• the Apex widget now also shows queued/running workflow activity for discussion, review, and negotiation work
• queue items are labeled with simple priority markers (P1 review, P2 negotiation, P3 discussion) plus queue order labels for waiting work
• the widget keeps a small recent transition log so you can see queued → started → finished/cancelled steps
• transition log entries are timestamped and color-coded for faster queue debugging
• finished/cancelled history entries include queue wait/runtime durations per workflow item
• the footer now shows separate wait/run queue badges for faster at-a-glance workflow monitoring
• the queue header now shows total elapsed time for the active phase (or oldest waiting item)
• each widget agent row includes a small live timer for the current action
• widget timers are color-coded so waiting/idle stays muted, active work is accent-colored, and warning states stand out
• final companion outcome still reaches the main agent through injected system prompt

chat-context

Best when you want the full visible transcript to become part of the conversation state.

• every Apex informational message is written to session
• every Apex informational message becomes part of context
• not only the final outcome

Project awareness

When enabled, Apex builds a compact project-context block from:

• top-level repo structure
• commonly important files (README.md, package.json, tsconfig.json, etc.)
• recently touched files
• files mentioned in the prompt
• target files involved in pending edits/writes

This helps companions critique implementation plans in a repo-specific way instead of giving generic advice.

Edit / Write review

When Review edits/writes is enabled, Apex intercepts pending edit and write tool calls, and also risky bash-based file mutations such as redirections (> / >>), tee, cp, mv, rm, touch, mkdir, ln, chmod, chown, chgrp, install, truncate, dd, git rm, git mv, git restore, git checkout --, sed -i, perl -pi, and Python write patterns like open(..., 'w') / Path(...).write_text(...), then asks companions to review them for:

• architecture fit
• correctness
• completeness
• missing related files
• security issues
• blind spots
• repo consistency
• quality vs expediency

The result is mapped through:

• verdict (APPROVE, WARN, BLOCK)
• severity (LOW, MEDIUM, HIGH, CRITICAL)
• inferred review categories (ARCHITECTURE, CORRECTNESS, COMPLETENESS, SECURITY, TESTS, CONSISTENCY)
• strictness (lenient, balanced, strict)
• blocking policy by severity

During review, the Apex status bar is continuously updated with aggregated catches by severity and by review category so you can see what the panel is detecting in real time.

In widget mode, the Apex widget also mirrors that live review activity and the queue state, so you can see which workflow is running now and which Apex work is still waiting behind it.

Apex also distinguishes shell mutation classes (content, filesystem, metadata, destructive) so harmless shell plumbing like 2>&1 is ignored while true filesystem-changing commands are reviewed more accurately.

When Apex blocks a change because it uncovered related follow-up work in nearby files, it can open a small repair window so the main agent can continue the wider fix with warnings instead of getting trapped in a non-ending block chain.

If the main agent immediately retries on a target file that matches any of the previous three blocked target files from the same turn, Apex skips re-running the review so the agent can apply the fix without paying for another near-identical review pass.

For more explicit coordination, the main agent can call apex_negotiate and propose a concrete contract: target files, planned changes, constraints, concessions, and a mutation budget. If Apex approves, it opens a scoped contract window so related follow-up edits can proceed without being repeatedly re-blocked.

before deciding whether to allow or block the mutation.

Apex also normalizes weak reviewer outputs using heuristics, so obviously dangerous/security-sensitive changes are escalated even if a model under-scores them.

Config example

{
  "agents": [
    {
      "name": "Sage",
      "icon": "🦉",
      "role": "Architect",
      "model": "claude-sonnet-4-5",
      "provider": "anthropic"
    },
    {
      "name": "Flint",
      "icon": "🔥",
      "role": "Pragmatist",
      "model": "gpt-5.1",
      "provider": "openai"
    }
  ],
  "discussionRounds": 1,
  "includeContext": true,
  "debug": false,
  "outputMode": "widget",
  "widgetVerbose": false,
  "projectAwareness": true,
  "reviewEditsAndWrites": true,
  "reviewStrictness": "balanced",
  "blockingBySeverity": {
    "LOW": "none",
    "MEDIUM": "partial",
    "HIGH": "block",
    "CRITICAL": "block"
  }
}

Intended use

Apex is designed for users who want the main agent to avoid:

• lazy fixes
• architecture drift
• under-reviewed edits
• repo-inconsistent implementations
• security blind spots

and instead converge toward stronger code through visible multi-agent pressure and review.

Publishing to npm

This extension is structured as a pi package and can be published to npm.

Pre-publish checklist

• verify package.json version
• verify package.json.pi.extensions points to ./index.ts
• verify runtime imports are covered by peerDependencies / dependencies
• run a dry-run package check:

npm pack --dry-run

• optionally test local installation with pi:

pi install /absolute/path/to/apex-companion-coding

Publish

npm login
npm publish

If you later move this package under an npm scope, publish it as public:

npm publish --access public

Install after publishing

pi install npm:pi-apex-companion-coding

Project-local:

pi install -l npm:pi-apex-companion-coding

License

This package uses the same license family as pi-mono: MIT. See LICENSE.