Local developer tool · MIT

Explicit state.
Less repeated history.

An HTTP proxy for agent workflows that can represent their progress as structured JSON. It replaces selected conversation history with a task specification, current state and the latest observation.

This is documentation for software you run yourself, not a hosted inference API. Model requests go to your configured upstream and may incur charges.

Set up locally Read the README

How the workflow changes

Your client sends a request to the local proxy. The proxy builds the upstream context around the task specification and session state, then extracts a state_patch from the model response.

{
  "state_patch": {
    "step": 2,
    "notes": "Checked the input format"
  },
  "action": "Continue with validation"
}

A state_patch must be a JSON object, not null, an array or a scalar. "state_patch": {} is a valid no-op. A recognized empty patch is not replaced by a later legacy marker. When multiple fenced objects are present, the first valid wrapped patch wins; actions from different blocks are not combined.

This is not a lossless transcript archive. Facts omitted from state may disappear from later requests. Arrays replace previous arrays; resend the full list when it must survive. A null patch value deletes its key.

Install and inspect

The npm package is skillstate-proxy. It exposes the commands skillstate and skillstate-proxy. Start by reading the installed version's help:

npm install -g skillstate-proxy
skillstate --version
skillstate --help

Configure your upstream URL and credentials locally, then start the proxy. The default listener is 127.0.0.1:8789; a compatible chat client uses http://127.0.0.1:8789/v1 as its API base.

# Set SKILLSTATE_UPSTREAM and SKILLSTATE_API_KEY
# in your local environment before starting.
skillstate --schema step,notes,findings

Choose a model available from your upstream and verify a short synthetic workflow before using sensitive data. A source checkout and the published npm package can contain different revisions.

HTTP reference

These routes describe the repository's interface, not certification of every provider or SDK. Check streaming, tool calls and translated requests against your exact client and model.

Local proxy routes
Method	Path	Purpose
POST	`/v1/chat/completions`	Chat-completion requests with state handling
POST	`/v1/messages`	Anthropic-format translation path
GET	`/v1/models`	Model listing from the configured upstream
GET	`/health`	Proxy and upstream circuit status
GET	`/state`	Session listing; use the session query parameter to inspect state
DELETE	`/state?session=ID`	Reset the specified session
GET	`/cost`	Recorded cost summary, not a provider invoice

Configuration and data handling

Start with the example configuration. The CLI supports --config, --upstream, --port, --schema and --verbose.

Environment settings
Variable	Purpose
`SKILLSTATE_UPSTREAM`	Upstream API base URL
`SKILLSTATE_API_KEY`	Upstream credential; never commit real keys
`SKILLSTATE_PORT`	Local listening port
`SKILLSTATE_SCHEMA`	Comma-separated allowed state keys
`SKILLSTATE_INITIAL_STATE`	Initial state as JSON
`SKILLSTATE_CONFIG`	Configuration file path
`SKILLSTATE_VERBOSE`	Verbose logging switch

For overlapping settings, CLI flags take precedence over environment variables, then the configuration file, then defaults. Consult the installed version's help for supported values.

Session state is persisted locally and can contain sensitive task information. The configured upstream receives the rewritten context. Keep the listener private, protect state and credentials, and review SECURITY.md before deployment.

Initial state, saved state and proposed patches are validated as plain JSON data. Non-finite numbers, getters, sparse arrays, custom objects and reserved prototype-related keys are rejected; nesting is limited to 64 levels. The configured state byte limit also applies at startup and when reloading sessions.

Saved-session reads reject invalid UTF-8, oversized records and final-component symbolic links. Invalid files are left in place for diagnosis rather than deleted during a read; an explicit later save or reset can replace or remove them. Keep the state directory and its parent directories private. These checks are not a sandbox or a distributed locking system.

Limits worth understanding

No guaranteed savings or accuracy. Results depend on workload, state design, model output, retries, output tokens and provider billing.
A list of allowed keys is not a size bound. Values, arrays and observations can still grow. Do not infer constant latency or a fixed token budget from the state pattern alone.
Not every workload fits. Avoid replacing the transcript when later steps need verbatim evidence, deferred details or a complete audit trail. Short conversations may cost more with state overhead.
Not a universal compatibility layer. Verify the paths you use, especially streaming, tool-result correlation, concurrent sessions and failure recovery.

Verification, not a static badge

Run the build and tests from a source checkout. The Actions history records individual runs and revisions; skipped integration checks are not proof of live compatibility.

npm ci
npm run build
npm test

The repository includes a conversation benchmark and a tool-loop benchmark. Running them against an external provider can cost money. Retain the revision, configuration, raw usage, quality results and failures before publishing a comparison.

The project draws on the SKILL.state paper. Research results and historical runs are not performance guarantees for this implementation.

Explicit state.Less repeated history.