openclaw/workspace/james

James Backbone (Redis + Watcher)

This folder implements the James event backbone and initial agents.

Implementation docs

• docs/AI_ACTION_PLAN.md
• docs/ARCHITECTURE.md
• docs/EVENTS.md
• docs/JAMES_REVIEW.md
• docs/MAIL_AGENT.md
• docs/NODES.md
• docs/POLICY.md
• docs/VOICE.md

Quick Start (Redis)

Redis runs as a native systemd service (redis-server.service). Auth and persistence are configured:

redis-cli -a "$REDIS_PASSWORD" ping

Credentials are in james/.env (gitignored).

Logging

All components use structured JSON logging to stderr (captured by systemd journal).

Output format (one JSON object per line):

{
  "ts": "2026-02-04T20:32:36+0100",
  "level": "info",
  "component": "james.watcher",
  "msg": "started",
  "channel": "james.events.system"
}

Set JAMES_LOG_LEVEL to DEBUG, INFO, WARNING, or ERROR (default: INFO).

View logs via journalctl:

journalctl --user -u james-watcher -f
journalctl --user -u james-analyst --since "1 hour ago"
journalctl --user -u james-audit --priority=err

Watcher (single node)

1. Install deps:

pip install -r requirements.txt

2. Run watcher:

PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host JAMES_ROLE=storage \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/agents/watcher/watcher.py

Pub/Sub test

Terminal A:

PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/subscribe_events.py

Terminal B:

PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/publish_event.py --type system.metrics --severity low --payload '{"test":true}'

Audit logger

Subscribes to all channels and writes JSON lines to james/audit/audit.log.

PYTHONPATH=~/clawd/workspace REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/tools/audit_logger.py

Analyst (local LLM)

Consumes james.events.* and publishes decisions to james.decisions.

PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
OLLAMA_MODEL=qwen2.5-coder \
python3 james/agents/analyst/analyst.py

Policy engine

Consumes james.decisions and emits james.actions with approval/deny/allow outcomes.

PYTHONPATH=~/clawd/workspace \
JAMES_NODE=main-host \
REDIS_URL=redis://:yourpass@127.0.0.1:6379/0 \
python3 james/agents/policy/policy_engine.py

Mail Agent (dry-run)

Reads mail fixtures and emits mail.* events to james.events.mail.

PYTHONPATH=~/clawd/workspace \
JAMES_MAIL_DRY_RUN=1 JAMES_MAIL_STDOUT=1 \
python3 james/agents/mail/mail_agent.py --dry-run

Voice Stub

Consumes actions/decisions and emits voice.* events to james.events.voice.

PYTHONPATH=~/clawd/workspace \
python3 james/agents/voice/voice_stub.py --stdout

Systemd (optional)

• systemd/james-redis.service runs the docker compose stack (not needed if using native redis).
• agents/watcher/systemd/james-watcher.service runs the watcher.
• agents/analyst/systemd/james-analyst.service runs the analyst.
• agents/policy/systemd/james-policy.service runs the policy engine.
• agents/mail/systemd/james-mail.service runs the mail agent.
• agents/voice/systemd/james-voice.service runs the voice stub.
• tools/systemd/james-audit.service runs the audit logger.

Install a unit:

cp agents/watcher/systemd/james-watcher.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now james-watcher

All services log structured JSON to the systemd journal.