playbooks

home / skills / plurigrid / asi / vers-agent

vers-agent skill

/skills/vers-agent

This skill helps manage ACP harnessed AI agents with session persistence and streaming via CLI/HTTP, improving debugging and workflow efficiency.

npx playbooks add skill plurigrid/asi --skill vers-agent

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: vers-agent
description: ACP-compliant AI agent harness with CLI/HTTP interface. Use when running Claude Code or other agents via unified protocol, managing sessions, or debugging agent workflows.
---

# vers-agent

ACP (Agent Client Protocol) harness for AI coding agents with session persistence and streaming.

## Quick Start

```bash
bun install && bun run build
export ANTHROPIC_API_KEY=sk-ant-...
./vers-agent
```

## Essential Commands (justfile)

| Action | Command |
|--------|---------|
| **Start everything** | `just up` |
| **Server only** | `just server` |
| **CLI only** | `just cli` |
| **Status dashboard** | `just status` |
| **Pre-commit check** | `just check` |
| **Nuclear reset** | `just nuke` |
| **One-shot prompt** | `just ask "your prompt"` |

## Modes

| Flag | Description |
|------|-------------|
| `./vers-agent` | Server + CLI (default) |
| `--server` | HTTP server only (:9999) |
| `--cli` | CLI connecting to localhost |
| `--url <host>` | CLI connecting to remote |
| `--local` | Local mode with debug logging |

## CLI Keybindings

- `Enter` - Submit | `Shift+Enter` - Newline
- `Tab` - Autocomplete | `Ctrl+C` - Cancel/Exit
- `@path` - File completion | `/cmd` - Commands

## Session Commands

- `/new` - New session | `/continue` - Resume last
- `/sessions` - List all | `/model` - Change model
- `/agent` - Switch agent | `/plan` - Toggle plan mode

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Port in use | `just kill-port` |
| Auth locked | `just reset-claim` |
| Full reset | `just nuke` |
| Complete wipe | `just pristine` |

## API Endpoints

- `POST /rpc` - JSON-RPC handler
- `GET /events` - SSE stream
- `GET /health` - Health check
- `GET /metrics` - Prometheus metrics

## Data Location

`~/.vers-agent/` contains sessions.db, tokens.json, config.json, and logs.

Overview

This skill is an ACP-compliant harness for running AI coding agents with a unified CLI and HTTP interface. It provides session persistence, streaming event handling, and JSON-RPC endpoints to run agents like Claude Code or other ACP-compatible models. Use it to manage agent sessions, debug workflows, and integrate agent-driven automation into toolchains.

How this skill works

The agent exposes a local HTTP server (default :9999) and a CLI that can connect locally or to a remote host. It handles JSON-RPC calls on /rpc, streams events over /events (SSE), and reports health and metrics via /health and /metrics. Sessions, tokens, config, and logs are stored under ~/.vers-agent/ for persistence and reproducibility; the CLI supports interactive session commands and keybindings for fast iteration.

When to use it

  • Running Claude Code or other ACP-compatible agents with a single unified protocol.
  • Developing or debugging agent workflows where session state and streaming output matter.
  • Integrating agent execution into CI or local automation via HTTP/JSON-RPC.
  • Testing multi-step plans or agent switching during development.
  • Operating in environments where session persistence across restarts is required.

Best practices

  • Run the server in a controlled environment and use the CLI for local interaction or scripts.
  • Keep API keys and tokens secured; the data directory (~/.vers-agent/) contains sensitive files.
  • Use the status dashboard and /metrics to monitor performance and resource usage.
  • Leverage one-shot prompts for quick tests (just ask ...) and session commands for longer workflows.
  • Use --local mode for verbose debug logging when diagnosing problems.

Example use cases

  • Start a local agent server to accept JSON-RPC requests from a CI job that performs code fixes.
  • Interactively develop an agent plan in the CLI, persist the session, and resume later for iterative debugging.
  • Stream agent outputs to a frontend via the /events SSE endpoint for live feedback during long runs.
  • Switch models or agents mid-session to compare responses without losing context.
  • Run automated scripts that call /rpc to trigger agent tasks and collect Prometheus metrics for observability.

FAQ

Where are sessions and tokens stored?

Data is stored in ~/.vers-agent/, including sessions.db, tokens.json, config.json, and logs.

How do I run just the server or CLI?

Use the provided flags: --server for HTTP server only, --cli for CLI only, or run the default binary for both.