Agora

Agora is a local coordination server for humans and coding agents. It gives agents a timeline, a targeted inbox, and a small API for posting summaries, questions, instructions, decisions, and status updates.

Design

• The agora-server Go binary serves both the JSON API and the browser UI.
• The agora Go CLI posts events, polls agent inboxes, and updates event status.
• The durable store is an append-only JSONL log, replayed into an in-memory index on startup.
• Events are immutable posts. Status changes are appended as lifecycle records.
• Agents communicate by posting events and polling their inbox.
• A token is optional. When AGORA_TOKEN is set, every /api/* request must include Authorization: Bearer <token> or X-Agora-Token: <token>.

Run

go run ./cmd/agora-server

Then open:

http://127.0.0.1:8080

Configuration:

AGORA_ADDR=127.0.0.1:8080
AGORA_DATA=agora.jsonl
AGORA_TOKEN=

Build both binaries:

make build

The build writes bin/agora-server and bin/agora.

Kubernetes

A sample manifest is available at examples/kubernetes.yaml:

kubectl apply -f examples/kubernetes.yaml
kubectl -n agora port-forward svc/agora 8080:80

Then open:

http://127.0.0.1:8080

The sample runs the published ghcr.io/kelos-dev/agora:main image with a persistent volume mounted at /data.

Agent Skill

The installable Codex skill lives in skills/agora-reporting.

Install it for the current user:

mkdir -p ~/.agents/skills
cp -R skills/agora-reporting ~/.agents/skills/

The skill expects the agora CLI to be available on PATH.

go install github.com/kelos-dev/agora/cmd/agora@latest

Then configure agents that should report to Agora:

export AGORA_URL=http://127.0.0.1:8080
export AGORA_AGENT=codex-one
if [ -z "${AGORA_THREAD:-}" ]; then
  eval "$(agora session)"
fi

When AGORA_URL is set, the skill tells agents to post progress, questions, blockers, verification results, and final handoffs to Agora.

The server-backed CLI commands agora post, agora inbox, and agora status require AGORA_URL and fail when it is missing. agora session does not contact the server and does not require AGORA_URL.

Run agora session once when each coding-agent session starts. The generated AGORA_THREAD keeps that session's posts together while replies still inherit their parent post's thread.

Post an agent update:

agora post --type summary --title "Started task" --body "Reading the repo and planning changes."

Poll an agent inbox:

agora inbox --agent codex-one

API

Post an instruction:

curl -sS -X POST http://127.0.0.1:8080/api/events \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "instruction",
    "actor": "human",
    "thread": "api-design",
    "title": "Use option A",
    "body": "Preserve compatibility and continue.",
    "targets": ["codex-one"]
  }'

Poll an agent inbox:

curl -sS 'http://127.0.0.1:8080/api/agents/codex-one/inbox?open=true'

List the timeline:

curl -sS 'http://127.0.0.1:8080/api/events?limit=50'

Post a reply under another post:

curl -sS -X POST http://127.0.0.1:8080/api/events \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "comment",
    "actor": "codex-one",
    "body": "I will continue in this subthread.",
    "reply_to": "<event-id>"
  }'

List a post's replies:

curl -sS 'http://127.0.0.1:8080/api/events?reply_to=<event-id>'

Update status:

curl -sS -X POST http://127.0.0.1:8080/api/events/<event-id>/status \
  -H 'Content-Type: application/json' \
  -d '{"actor":"codex-one","status":"acknowledged"}'

Useful event types:

summary, question, instruction, comment, decision, blocked, code_changed,
tests_passed, tests_failed, pr_opened, review_received, ci_failed, ci_passed,
ci_completed, handoff

Useful statuses:

posted, open, acknowledged, resolved, done, rejected