Spice

Agents can execute.

But they don’t know what to do next.

Spice is a decision-layer runtime — a brain above agents, inspired by the rise of execution agents like Claude Code, Codex, Hermes, and OpenClaw, and by the idea of a world model.

Spice controls agent actions before execution.

It turns messy context into source-backed, comparable, approval-aware decisions — before handing work to executors like Claude Code, Codex, Hermes, or OpenClaw.

It helps you decide what should happen next, why that option is better, and what evidence supports it.

While execution agents are getting better at doing things,

Spice focuses on the missing layer:

👉 What should be done next — and why.

❗️ 30s Dogfooding example

In this demo, Spice is used to decide its own next step: improving state-as-context, strengthening read-only workspace perception, or expanding executor handoff.

The default view stays conversational, while /details expands the full auditable Decision Card.

⚡ Why it matters

Today, we have powerful agents that can do almost anything:

• write code
• analyze data
• browse tools
• automate workflows
• hand off tasks to other systems

But in most agent systems, decision and execution are tightly coupled.

Most agent benchmarks measure the final task result.

That is useful, but it also means decision quality is usually inferred indirectly from outcomes:

final result = decision quality + tool ability + execution reliability + environment conditions

When a task succeeds or fails, the most important part is often hard to inspect:

Why was this action chosen?

Spice separates the decision layer from the execution layer.

Before an agent acts, Spice turns the next action into a source-backed, comparable, approval-aware decision:

• what options were considered
• what evidence supports them
• why one action was selected
• what trade-offs were rejected
• whether execution should require approval

Execution agents answer: how do we do it?

Spice answers: should we do it, and why?

🧠 What is Spice?

Spice is a decision runtime for agentic AI systems.

It gives AI systems a structured loop:

perception → state model → simulation → decision → execution → reflection

It allows AI systems to:

• understand context (Decision relevant state)
• reason about possible futures (simulation)
• make structured decisions (decision)
• delegate actions to agents (execution)
• learn from outcomes (Decision Evolution)

Spice does not replace agents like Claude Code, Codex, Hermes, or OpenClaw.

It gives them an auditable, traceable, and evolving decision layer before execution.

🎬 Demo of Spice

To gain a more intuitive understanding of Spice,

please visit our carefully prepared demo about conflicts between life and work events: Spice-live-demo

Demo Video

1. Bilibili

Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds.

2. YouTube

Click the image to watch the full demo video of using Spice to handle conflicts between the digital and physical worlds.

👨‍🔧 Spice: Decision Layer Architecture

🧭 Decision Guidance: decision.md

The easiest way to use Spice locally is the interactive decision shell:

spice setup
spice shell

In a workspace initialized by spice setup, local decision guidance lives at:

.spice/decision.md

decision.md tells Spice how to compare candidate decisions within the capabilities supported by the active runtime and policy adapter.

It can guide:

• what Spice optimizes for
• how trade-offs are weighted
• which constraints should matter
• what kinds of decisions should be preferred or avoided

decision.md is decision guidance.

It is not:

• memory
• a prompt dump
• an execution script
• an agent workflow
• a tool permission file

Editing decision.md can change how Spice ranks and explains options, but it does not grant execution capability. Execution still goes through runtime guardrails, approval boundaries, and configured executors.

A typical flow looks like:

spice setup
$EDITOR .spice/decision.md
spice shell

Then ask Spice what to do next:

spice> Read this repo and tell me what we should prioritize next.

Spice will respond conversationally by default, while keeping the full audit trail available through commands like:

/details    expand the full Decision Card
/sources    show evidence used
/why        explain trade-offs
/sim        show simulation
/json       inspect raw artifacts

Advanced profile/demo flows may also use .spice/decision/decision.md, especially in the older quickstart and domain-adapter examples. For the current interactive runtime, .spice/decision.md is the default local decision guidance file.

See docs/decision.md and docs/decision_quickstart.md for the full guidance contract.

⚙ Install

Install from source

git clone https://github.com/Dyalwayshappy/Spice.git
cd Spice

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -U pip
pip install -e .

Then verify:

spice --help

Install from PyPI (stable, recommended)

pip install spice-runtime

Then verify the CLI:

spice --help

Upgrade

pip install -U spice-runtime

🚀 Quick Start

The fastest way to try Spice is the interactive decision shell.

pip install spice-runtime
spice setup
spice shell

spice setup initializes a local Spice workspace:

.spice/
  config.json          # LLM / executor / perception config
  decision.md          # user-editable decision guidance
  state/state.json     # local decision state
  sessions/            # conversation/session records
  runs/                # run artifacts
  decisions/           # Decision Cards
  perceptions/         # workspace / URL / delegated perception artifacts
  investigations/      # read-only investigation consent and records
  approvals/           # approval checkpoints
  outcomes/            # execution outcomes
  conversations/       # shell conversation turns
  memory/              # decision memory and summaries
  cache/               # runtime cache
  executors/           # local executor metadata/config
  skills/              # local skill metadata
  .env                 # optional saved API keys, if configured during setup

Then start a session:

spice shell

Try:

spice> Read this repo and tell me what we should prioritize next.
spice> Why not option B?
spice> Give me a two-week plan for A.
spice> /execute <approval_id>

By default, Spice responds conversationally and keeps the audit card folded.

Useful shell commands:

/details     expand the full Decision Card
/sources     show evidence and sources used
/why         explain why the selected option won
/sim         show simulation metadata
/json        inspect raw artifacts
/context     inspect compiled decision context
/workspace   inspect workspace perception
/refine      adjust the latest decision
/execute     request approval-gated execution
/help        show shell commands

1. Configure A Model

You can configure an LLM during spice setup, or later:

spice config enable-llm \
  --provider openrouter \
  --model minimax/minimax-m2.7

Spice will read the API key from the provider-specific environment variable.

Example:

export OPENROUTER_API_KEY="your-openrouter-api-key"
spice shell

Supported LLM providers: