casp_skill

This skill enables automated control of the codex app-server via a v2 proxy, streaming JSONL, auto approvals, and multi-instance orchestration.

Python

42

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill tkersey/dotfiles --skill casp

SKILL.md7.6 KB

Overview

This skill runs a v2-only Node JSONL proxy that spawns codex app-server and exposes an automation-friendly stream API. It provides an evented, lossless JSONL stream, deterministic timeout handling for forwarded server requests, and auto-accepts v2 approvals so orchestrators can drive sessions programmatically. Each instance is a proxy + one app-server child, enabling parallel isolated sessions.

How this skill works

The proxy performs the app-server handshake (initialize -> initialized) with experimentalApi enabled, reads/writes JSONL over stdio, and forwards messages between the app-server and your orchestrator. It auto-handles v2 approval flows, rejects legacy approval types, and emits typed events (casp/ready, casp/fromServer, casp/serverRequest, etc.) that include raw wire messages plus derived routing keys. Forwarded server requests must be answered by the orchestrator or will fail after a configurable timeout.

When to use it

Programmatic automation or orchestration of codex app-server sessions
Running multiple parallel, isolated app-server instances (N proxy+server pairs)
Mining or indexing sessions, threads, and turns with deterministic event routing
Steering or resuming active turns (turn/steer, thread/resume) from external agents
Integrating dynamic tools or auto-handling server-initiated tool calls and auth refresh

Best practices

Start each parallel instance with its own --state-file or state-file-dir to avoid shared state
Consume casp/fromServer as the source of truth; use included msg for lossless replay
Reply only to casp/serverRequest events and use matching id in casp/respond to avoid timeouts
Use the client helpers (casp_client.mjs) for typed intent rather than raw method strings
Tune --server-request-timeout-ms for deterministic failure semantics; 0 disables timeout

Example use cases

Run N isolated app-server sessions to parallelize workload or load-test orchestration logic
Have subagents send code patches or updates into live sessions via casp/request
Automate approvals and execpolicy amendments while forwarding tool calls to orchestrator tools
Mine thread and turn inventories (thread/list, thread/read) for offline indexing
Steer active conversations programmatically using turn/steer and thread/resume

FAQ

No. The proxy spawns codex app-server and manages state under ~/.codex/casp by default; passing --cwd controls where the app-server runs.

How are server-initiated tool calls handled?

casp emits casp/serverRequest for tool calls. Run the tool in your orchestrator and reply with casp/respond; casp will fail the request after the configured timeout if you don't reply.