Skip to content

AutoAgent, Forge's Autonomous Multi-Agent Subsystem

URL: https://mkdocs.justinsforge.com/autoagent/

Status: scaffolding only as of 2026-05-02. No working code yet. This README defines the architecture so the next session can drop real implementation onto a stable layout.

What it is

/AutoAgentProject runs a bounded autonomous mission with multiple Claude-powered agents collaborating without human intervention. Each agent is a systemd unit firing claude -p on a tick. State lives in files. Justin watches via a dedicated reporter agent that batches updates to Telegram, plus a read-only bridge dashboard.

This is intentionally separate from the existing forge fleet (Telegram bots, dispatcher, /spawn sessions). Those are human-in-the-loop or one-shot. AutoAgent is for hands-off multi-hour work.

Hierarchy

Justin
   ↑↓ (Telegram, batched + priority-filtered)
AutoAgent-Reporter        translates manager state to human-readable updates
   ↑↓ (state.json, file-mediated)
AutoAgent-Manager         owns the goal, decomposes into plan, assigns work
   ↑↓ (per-agent inbox/outbox files)
AutoAgent-CodeBuilder-N   ┐
AutoAgent-Designer        │
AutoAgent-UI              │ specialists, narrow tool surface, one job each
AutoAgent-Ideator         │ (brainstorms options, hands brief to manager)
...                       ┘
   +
AutoAgent-Quota           kill switch, watches subscription burn, halts on budget exceeded

Manager reads only state.json per tick (status + detail split). Specialists write 1-line status to state.json plus dump detail to their own files. Sub-managers are intentionally not in v1; introduce only if specialist count exceeds ~7-8 or the project goes multi-domain.

Layout

Path Purpose Git?
autoagent/core/ Python framework (CLI, manager, reporter, specialist, quota, state helpers) yes
autoagent/prompts/ Role briefing templates (manager.md, reporter.md, specialists/*.md) yes
autoagent/systemd/ Unit templates installed to /etc/systemd/system/ yes
autoagent/bridge/ Read-only dashboard backend (built later) yes
autoagent/docs/ Architecture doc, runbook, design decisions yes
data/autoagent/<project-id>/ Per-project runtime state (goal, plan, state, events, agents/) no, gitignored
logs/autoagent/<project-id>/ Per-agent stdout/stderr, logrotate-managed no, gitignored via existing logs/ rule
autoagent-missions/<project-id>/ The mission workdir: the only place agents may write yes, tracked

Agents have read access to all of /home/justinwieb/forge/ (brands, prior sites, code patterns) but write access only inside their mission workdir. systemd WorkingDirectory= is set per-unit so pwd defaults there. Write-isolation is enforced by prompt + observability (git status after a run reveals any violation).

Quota guardrails (non-negotiable)

  • Per-project quota budget set at start time, defaults to 10% of daily subscription.
  • forge-autoagent-<id>-quota.service polls quota tracker every minute.
  • If budget exceeded: systemctl stop forge-autoagent-<id>-*. Hard kill, no negotiation. Reporter sends one final ping.
  • Specialists CANNOT spawn other specialists without manager approval (manager itself cannot deviate from original goal without reporter relaying approval request to Justin).

Reporter batching rules

  • Routine ticks: silent (writes to events.log + bridge dashboard only).
  • Milestone ticks (plan step complete): one bundled Telegram message.
  • Blocker ticks (specialist unrecoverable error, quota >80%, manager wants goal deviation): immediate ping.
  • End of mission: always.

CLI

/AutoAgentProject start <project-id> "<goal>" [--budget 10%] [--max-hours 4] [--specialists codebuilder:2,designer:1,ui:1]
/AutoAgentProject status <project-id>
/AutoAgentProject abort <project-id>
/AutoAgentProject list

Reporter Telegram channel

  • Bot: @forge_autoagent_reporter_bot
  • Token: ~/.forge-secrets/telegram-autoagent-reporter.env
  • Authorized user: Justin (id 7110798439)
  • Dedicated bot (not folded into @forge_notify_outbound_bot) so per-project mute is possible during long autonomous runs.

What's not here yet

  • Any Python code in core/
  • Prompt templates in prompts/
  • systemd unit templates in systemd/
  • Bridge dashboard
  • First test mission scoping

Open the next session by deciding the reporter channel + picking a low-stakes first test mission, then start dropping code into core/.

Doctrine alignment

  • Section 8 flat-with-verbose-filenames: respected for code, all framework files will be forge_autoagent_*.py flat in core/ (no nested submodules).
  • Section 3 naming: kebab-case forge-autoagent-<project-id>-<role> for systemd units; user-facing AutoAgent-Manager etc. CamelCase.
  • Section 9.5 robust-over-quick: quota guard + worktree isolation are not optional; no "we'll add safety later."
  • Section 12 memory: per-project runtime state is NOT memory, it's runtime data; lives in forge/data/autoagent/, not memory/.