CIA - Central Intelligence Agent

Manage background agents directly in your Elixir app.

Overview

CIA is an opinionated library for running background agents from an Elixir app.

It separates two runtime concerns:

• the harness: what agent implementation is running
• the sandbox: where that agent is running

And it manages three core runtime models:

• agents: a single running managed agent
• threads: a conversation handle owned by an agent
• turns: a single unit of model work on a thread

Each agent runs as a supervised GenServer under CIA.AgentSupervisor. Right now, CIA is entirely in-memory. Agent, thread, and turn state does not survive application restarts.

Installation

Install from GitHub for now:

def deps do
  [
    {:cia, github: "seanmor5/cia"}
  ]
end

Usage

# Start an agent
{:ok, agent} = CIA.start(
  harness: :codex,
  sandbox: :local
)

# Subscribe to events
:ok = CIA.subscribe(agent)

# Create a thread
{:ok, thread} = CIA.thread(agent,
  cwd: "/sandbox",
  model: "gpt-5.4",
  system_prompt: "You write concise, correct Elixir.",
  metadata: %{label: "main"}
)

# Submit a turn
{:ok, turn} = CIA.turn(agent, thread, "Implement a linked list in C")

# Steer or interrupt mid-turn
:ok = CIA.steer(agent, turn, "Add tests as well")
{:ok, turn} = CIA.cancel(agent, turn)

# Stop the agent
:ok = CIA.stop(agent)

Events

CIA supports agent-level subscriptions through subscribe/2.

Subscribers currently receive messages in this form:

{:cia, %CIA.Agent{}, event}

The current event stream forwards harness-originated events from the running agent process, for example:

{:cia, agent, {:harness, :codex, payload}}

Subscriptions are for all agent events.

Supported Harnesses

CIA currently just supports codex via it's app-server implementation.

Supported Sandboxes

CIA currently supports :local and :sprite (see Sprite) based sandboxes.