acpx 0.1.0 → 0.1.2

package/LICENSE

@@ -1,15 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+Copyright (c) 2026 Janitr AI
 
-       http://www.apache.org/licenses/LICENSE-2.0
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,102 +1,164 @@
 # acpx
 
-Headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) — talk to coding agents from the command line.
+Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤
+
+`acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping.
+
+One command surface for Codex, Claude, Gemini, OpenCode, Pi, or custom ACP servers. Built for agent-to-agent communication over the command line.
+
+- **Persistent sessions**: multi-turn conversations that survive across invocations, scoped per repo
+- **Named sessions**: run parallel workstreams in the same repo (`-s backend`, `-s frontend`)
+- **Prompt queueing**: submit prompts while one is already running, they execute in order
+- **Fire-and-forget**: `--no-wait` queues a prompt and returns immediately
+- **Structured output**: typed ACP messages (thinking, tool calls, diffs) instead of ANSI scraping
+- **Any ACP agent**: built-in registry + `--agent` escape hatch for custom servers
+- **One-shot mode**: `exec` for stateless fire-and-forget tasks
 
 ```bash
-# One-shot: run a prompt against Codex, stream output, exit when done
-acpx run --agent codex-acp --cwd ./my-project "Refactor the auth module"
-
-# Multi-turn: create a session, send messages
-acpx session create --agent codex-acp --cwd ./my-project
-acpx session send <id> "Refactor the auth module"
-acpx session send <id> "Now add tests"
-acpx session close <id>
-```
+$ acpx codex "find the flaky test and fix it"
+
+[thinking] Investigating test suite for flaky failures
+
+[tool] Run npm test -- --reporter=verbose (running)
+[tool] Run npm test -- --reporter=verbose (completed)
+  output:
+    ✓ auth.login (0.8s)
+    ✗ checkout.submit (timed out after 5000ms)
+    ✓ cart.add (0.3s)
+
+[thinking] Found it — checkout.submit has a race condition in the async setup
 
-## Why?
+[tool] Edit src/checkout.test.ts (completed)
+  output:
+    Success. Updated 1 file.
 
-ACP adapters exist for every major coding agent ([Codex](https://github.com/zed-industries/codex-acp), [Claude Code](https://github.com/zed-industries/claude-code-acp), [Gemini CLI](https://github.com/google-gemini/gemini-cli), etc.) but every ACP client is a GUI app or editor plugin.
+[tool] Run npm test -- checkout.submit (completed)
+  output:
+    ✓ checkout.submit (0.4s)
 
-`acpx` is the missing piece: a simple CLI that lets **agents talk to agents** (or humans script agents) over structured ACP instead of scraping terminal output.
+Fixed: added `await` to the setup hook in checkout.submit. The test was
+reading stale state from the previous run.
+
+[done] end_turn
+```
 
 ## Install
 
 ```bash
-npm install -g acpx
-# or
-npx acpx run --agent codex-acp "Hello"
+npm i -g acpx
 ```
 
-### Prerequisites
+`acpx` manages persistent sessions, so prefer a global install. Avoid `npx acpx ...` for normal use.
 
-You need an ACP-compatible agent installed:
+## Agent prerequisites
 
-```bash
-# Codex
-npm install -g @zed-industries/codex-acp
+`acpx` auto-downloads ACP adapters with `npx` on first use. You do not need to install adapter packages manually.
 
-# Claude Code
-npm install -g @zed-industries/claude-code-acp
+The only prerequisite is the underlying coding agent you want to use:
 
-# Gemini CLI (native ACP support)
-npm install -g @google/gemini-cli
-```
+- `acpx codex` -> Codex CLI: https://codex.openai.com
+- `acpx claude` -> Claude Code: https://claude.ai/code
+- `acpx gemini` -> Gemini CLI: https://github.com/google/gemini-cli
+- `acpx opencode` -> OpenCode: https://opencode.ai
+- `acpx pi` -> Pi Coding Agent: https://github.com/mariozechner/pi
 
-## Usage
-
-### One-shot (`run`)
+## Usage examples
 
 ```bash
-# Simple prompt
-acpx run --agent codex-acp --cwd /repo "Fix the failing tests"
+acpx codex 'fix the tests'                     # implicit prompt (persistent session)
+acpx codex prompt 'fix the tests'              # explicit prompt subcommand
+acpx codex --no-wait 'draft test migration plan' # enqueue without waiting if session is busy
+acpx exec 'summarize this repo'                # default agent shortcut (codex)
+acpx codex exec 'what does this repo do?'      # one-shot, no saved session
+
+acpx codex -s api 'implement cursor pagination' # named session
+acpx codex -s docs 'rewrite API docs'           # parallel work in another named session
 
-# Auto-approve all tool calls
-acpx run --agent codex-acp --cwd /repo --approve-all "Build a REST API"
+acpx codex sessions              # list sessions for codex command
+acpx codex sessions list         # explicit list
+acpx codex sessions close        # close cwd-scoped default session
+acpx codex sessions close api    # close cwd-scoped named session
 
-# JSON output for programmatic use
-acpx run --agent codex-acp --cwd /repo --format json "Add logging"
+acpx claude 'refactor auth middleware' # built-in claude agent
+acpx gemini 'add startup logging'      # built-in gemini agent
 
-# Pipe prompt from stdin
-echo "Refactor to async/await" | acpx run --agent codex-acp --cwd /repo
+acpx my-agent 'review this patch'                      # unknown name -> raw command
+acpx --agent './bin/dev-acp --profile ci' 'run checks' # --agent escape hatch
 ```
 
-### Multi-turn sessions
+## Practical scenarios
 
 ```bash
-# Create session
-acpx session create --agent codex-acp --cwd /repo
-# → abc123
+# Review a PR in a dedicated session and auto-approve permissions
+acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
+  'Review PR #842 for regressions and propose a minimal fix'
 
-# Send messages (streams results, exits on completion)
-acpx session send abc123 "Refactor the auth module"
-acpx session send abc123 "Now add tests for it"
+# Keep parallel streams for the same repo
+acpx codex -s bugfix 'isolate flaky checkout test'
+acpx codex -s release 'draft release notes from recent commits'
+```
 
-# List sessions
-acpx session list
+## Global options in practice
 
-# Close when done
-acpx session close abc123
+```bash
+acpx --approve-all codex 'apply the patch and run tests'
+acpx --approve-reads codex 'inspect repo structure and suggest plan' # default mode
+acpx --deny-all codex 'explain what you can do without tool access'
+
+acpx --cwd ~/repos/backend codex 'review recent auth changes'
+acpx --format text codex 'summarize your findings'
+acpx --format json codex exec 'review changed files'
+acpx --format quiet codex 'final recommendation only'
+
+acpx --timeout 90 codex 'investigate intermittent test timeout'
+acpx --verbose codex 'debug why adapter startup is failing'
 ```
 
-### Output formats
+## Output formats
 
-| Format | Flag | Description |
-|--------|------|-------------|
-| text | `--format text` | Human-readable streaming (default) |
-| json | `--format json` | Structured ndjson for machines |
-| quiet | `--format quiet` | Final text output only |
+```bash
+# text (default): human-readable stream with tool updates
+acpx codex 'review this PR'
 
-## How it works
+# json: NDJSON events, useful for automation
+acpx --format json codex exec 'review this PR' \
+  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'
 
+# quiet: final assistant text only
+acpx --format quiet codex 'give me a 3-line summary'
 ```
-┌─────────┐     stdio/ndjson     ┌──────────────┐     wraps      ┌─────────┐
-│  acpx   │ ◄──────────────────► │  ACP adapter  │ ◄───────────► │  Agent   │
-│ (client) │    ACP protocol     │ (codex-acp)   │               │ (Codex)  │
-└─────────┘                      └──────────────┘               └─────────┘
+
+## Built-in agents and custom servers
+
+Built-ins:
+
+| Agent      | Adapter                                                                | Wraps                                                 |
+| ---------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
+| `codex`    | [codex-acp](https://github.com/zed-industries/codex-acp)               | [Codex CLI](https://codex.openai.com)                 |
+| `claude`   | [claude-agent-acp](https://github.com/zed-industries/claude-agent-acp) | [Claude Code](https://claude.ai/code)                 |
+| `gemini`   | native                                                                 | [Gemini CLI](https://github.com/google/gemini-cli)    |
+| `opencode` | native                                                                 | [OpenCode](https://opencode.ai)                       |
+| `pi`       | [pi-acp](https://github.com/svkozak/pi-acp)                            | [Pi Coding Agent](https://github.com/mariozechner/pi) |
+
+Use `--agent` as an escape hatch for custom ACP servers:
+
+```bash
+acpx --agent ./my-custom-acp-server 'do something'
 ```
 
-acpx spawns the ACP adapter as a child process, communicates over the ACP protocol (JSON-RPC over stdio), and translates structured events (tool calls, text, permissions) into CLI output.
+## Session behavior
+
+- Prompt commands use saved sessions scoped to `(agent command, cwd, optional name)`.
+- `-s <name>` creates/selects a parallel named session in the same repo.
+- Prompt submissions are queue-aware per session. If a prompt is already running, new prompts are queued and drained by the running `acpx` process.
+- `--no-wait` submits to that queue and returns immediately.
+- `exec` is always one-shot and does not reuse saved sessions.
+- Session metadata is stored under `~/.acpx/sessions/`.
+
+## Full CLI reference
+
+See `docs/CLI.md`.
 
 ## License
 
-Apache-2.0
+MIT