Valor

An autonomous AI coworker. Not an assistant, not a chatbot — a colleague that owns its own machine and does real work.

• Works where you work. Receives tasks via Telegram or Email and replies in the same thread — no context switching, no dashboards to check.
• Ships code end-to-end. Plans a feature, critiques the plan, writes the code, runs tests, opens a PR, and merges it — without being babysat through each step.
• Remembers across sessions. A subconscious memory system injects relevant past decisions and corrections as <thought> blocks at exactly the right moment.
• Fixes itself. A watchdog + self-healing pipeline restarts on crashes, hibernates on API failures, and escalates to you only when automation can't recover.
• Extensible by design. Add a new skill in .claude/skills/, wire a tool in tools/ + MCP, or connect a new comms channel in bridge/ — the architecture absorbs extensions without surgery.

Valor wraps agent harnesses (like Claude Code) and bridges them to the comms channels humans actually use (Telegram, Email, LinkedIn, and more). The supervisor assigns work and provides direction. Valor executes autonomously on its own Mac, reaching out when necessary.

Three layers:

• Comms layer — bridges to the channels where work actually happens: Telegram, Email, LinkedIn, etc. Messages come in, replies go out, session context survives across conversations.
• Harness layer — wraps agent harnesses like Claude Code, giving Valor tools, memory, skills, and a full SDLC workflow.
• Execution layer — a standalone worker service runs sessions against the configured harness. Sessions come in three role flavors: PM (orchestrates work), Dev (writes code), and Teammate (conversational).

See docs/features/bridge-worker-architecture.md for the full design.

📸 TODO: Add demo GIF or screenshot here — see docs/assets/ for placement instructions.

Valor ships real features through a structured pipeline — a directed cyclic graph with failure cycles, not a straight line. Each stage is a skill the agent invokes, and each stage runs on the model best suited to its cognitive load: Opus for hard reasoning (Plan, Critique, Review) and Sonnet for plan execution and tool-heavy work (Build, Test, Patch, Docs).

• Cycles are first-class. Critique loops back to Plan when concerns surface. Test→Patch→Test iterates until the fix holds. Review→Patch→Test→Review repeats until findings clear.
• Hard patches resume the builder. When a Patch needs the original builder's accumulated context, PM resumes the Build session's Claude Code transcript instead of starting fresh — the dashed edge in the diagram.
• PM orchestrates, Dev executes. A read-only PM session steers the pipeline stage-by-stage; each stage spawns a full-permission Dev session that runs one skill and reports back.

The pipeline graph is defined in agent/pipeline_graph.py. See .claude/skills/sdlc/SKILL.md for the ground truth on stage definitions and docs/features/pipeline-graph.md for the feature doc.

# 1. Install dependencies
pip install -e .

# 2. Configure environment (symlink to vault)
ln -sf ~/Desktop/Valor/.env ~/src/ai/.env
# All secrets live in ~/Desktop/Valor/.env (iCloud-synced vault)

# 3. Start the bridge and worker
./scripts/start_bridge.sh
./scripts/valor-service.sh worker-start

./scripts/valor-service.sh status          # Bridge status
./scripts/valor-service.sh restart         # Restart bridge after code changes
./scripts/valor-service.sh worker-status   # Worker status
./scripts/valor-service.sh worker-restart  # Restart worker
tail -f logs/bridge.log                    # Stream logs

ai/
├── agent/               # Session queue, SDK client, output routing
├── bridge/              # Comms bridges (Telegram, etc.) and nudge loop
├── worker/              # Standalone worker service (python -m worker)
├── tools/               # Local Python tools
├── ui/                  # Dashboard web UI
├── monitoring/          # Watchdog, crash tracker, health checks
├── .claude/
│   ├── skills/          # SDLC and utility skills
│   ├── commands/        # Slash commands
│   └── agents/          # Subagent definitions
├── config/              # identity.json, persona segments, projects.json
├── scripts/             # Service management, setup, deployment
├── docs/features/       # Feature-level documentation
└── tests/               # Unit, integration, e2e

pytest tests/unit/ -n auto     # Fast unit tests in parallel
pytest tests/                  # Full suite
python -m ruff format .        # Format