# humanerd-drew/opencode-drewgent architecture

> Architecture diagram of the GitHub repository humanerd-drew/opencode-drewgent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/humanerd-drew/opencode-drewgent
- Repository: https://github.com/humanerd-drew/opencode-drewgent

## Overview

#### Purpose and Entry Points
This is a forkable local **opencode AI-agent runtime template**, not a conventional application. It configures agent identity, instructions, specialized subagents, durable knowledge, scheduled automation, and optional Discord access. Primary interactive entry is `opencode` after `scripts/setup.sh`; operational entry points include `scripts/discord_bot.py`, `scripts/drewgent_cron.py`, and `cron/cron_agent.py`.

#### Agent Configuration and Governance
`opencode.jsonc` is the runtime integration/configuration boundary. Repository-level rules and operating conventions live in `AGENTS.md` and `.opencode/instructions/00-architecture.md`. The vault-like identity hierarchy separates immutable behavioral rules, persona, and self-model:
- `@identity/brain/rules.md`
- `@identity/persona/SOUL.md`
- `@identity/SELF_MODEL.md`

This implements priority-based governance: brain/rules override persona and task-level preferences; tiered autonomy limits which changes the agent may perform without human approval.

#### Delegation and Specialist Agents
The orchestrated agent delegates work to focused profiles under `.opencode/agents/`, including planner, explorer, implementer, reviewer, SRE, and analyst:
- `.opencode/agents/orchestrator.md`
- `.opencode/agents/implementer.md`
- `.opencode/agents/reviewer.md`

Profiles encode role boundaries, model/cost intent, and permissions (notably read-only exploration/review versus editing). Isolated, parallel work is routed through the GJC delegation tool at `.opencode/tools/delegate.ts`; same-context tasks use opencode-native delegation. This is the main control-flow boundary between planning, execution, and quality gate stages.

#### Knowledge, Memory, and Skills
Long-term agent knowledge is filesystem-backed and tool-accessible rather than embedded in application code. Memory operations and graph retrieval are exposed through:
- `.opencode/plugins/knowledge.js`
- `.opencode/tools/remember.ts`
- `.opencode/tools/recall.ts`

`skills/` is the primary on-demand capability catalog: each skill’s `SKILL.md` supplies workflow instructions and may include scripts/references. `@action/skills/` is a bundled/action-oriented skill layer. The expected flow is request → select relevant skill/profile → retrieve provenance and memory → execute → write reusable facts or artifacts back to the knowledge system.

#### Proactive Automation and Work Persistence
Scheduled work is configured in `cron/jobs.json` and executed by scheduler/runtime modules:
- `cron/scheduler.py`
- `cron/jobs.py`
- `scripts/drewgent_cron.py`

Operational scripts handle cron health, self-healing, log rotation, knowledge ingestion, graph queries, and Kanban dispatch/worker execution. Kanban provides persistence across agent/session failure, with work intended to progress through explorer → implementer → reviewer. Key runners are `scripts/run_kanban_worker.py` and `scripts/kanban_maintenance.py`.

#### External Interfaces and Services
The Discord gateway maps Discord threads to persistent opencode sessions and streams agent activity:
- `scripts/discord_bot.py`
- `scripts/discord_send.py`

It requires `DISCORD_BOT_TOKEN`. Configured MCP boundaries include local codebase-memory graph access, Gajae-Code worktree/tmux coordination, Safari browsing, Discord, and WordPress; a remote Astryx design-system server is also documented. Environment secrets/configuration are expected through `.env` based on `.env.example`.

#### Deployment and Runtime Infrastructure
The main runtime is opencode plus Python automation, with Node.js used where needed (for example, the WhatsApp bridge under `scripts/whatsapp-bridge/`). Persistent background execution is platform-native:
- `services/launchd/ai.yourgent-opencode.plist.example`
- `services/systemd/yourgent-opencode.service`
- `services/windows/setup-scheduled-tasks.ps1`

GitHub Actions cover tests, Nix, Docker publishing, supply-chain auditing, and docs/site deployment. The repository is therefore a configurable local agent operating environment whose durable state and behavior are chiefly defined by Markdown/JSON configuration, skill content, and external opencode/MCP services.

Main entry points: [`.opencode/agents/orchestrator.md`](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/orchestrator.md) (Orchestrator profile), [`cron/scheduler.py`](https://github.com/humanerd-drew/opencode-drewgent/blob/main/cron/scheduler.py) (Cron scheduler), [`.opencode/plugins/knowledge.js`](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/plugins/knowledge.js) (Knowledge service), [`opencode.jsonc`](https://github.com/humanerd-drew/opencode-drewgent/blob/main/opencode.jsonc) (Runtime integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_runtime_config["Runtime integration<br/>JSONC config<br/>[opencode.jsonc]"]
  node_repo_rules["Repository rules<br/>operating guidance<br/>[AGENTS.md]"]
  node_architecture_rules["Architecture instructions<br/>[00-architecture.md]"]
  node_identity["Identity hierarchy<br/>durable identity<br/>[rules.md]"]
end

subgraph group_agents["Agent Control"]
  node_orchestrator{{"Orchestrator profile<br/>agent profile<br/>[orchestrator.md]"}}
  node_implementer["Implementer profile<br/>editing specialist<br/>[implementer.md]"]
  node_reviewer["Reviewer profile<br/>quality specialist<br/>[reviewer.md]"]
  node_gjc_delegate["GJC delegation<br/>parallel work tool<br/>[delegate.ts]"]
end

subgraph group_knowledge["Knowledge &amp; Skills"]
  node_knowledge_plugin[("Knowledge service<br/>opencode plugin<br/>[knowledge.js]")]
  node_memory_tools["Remember / recall<br/>knowledge tools<br/>[remember.ts]"]
  node_skills["Skill catalog<br/>on-demand workflows"]
end

subgraph group_automation["Automation &amp; Work"]
  node_cron_jobs["Scheduled jobs<br/>job definitions<br/>[jobs.json]"]
  node_scheduler["Cron scheduler<br/>Python scheduler<br/>[scheduler.py]"]
  node_kanban_worker["Kanban worker<br/>work runner"]
end

subgraph group_interfaces["Interfaces &amp; Runtime"]
  node_opencode{{"opencode runtime<br/>agent runtime"}}
  node_discord_gateway["Discord gateway<br/>bot gateway<br/>[discord_bot.py]"]
  node_environment["Environment secrets<br/>environment config<br/>[.env.example]"]
  node_service_hosts["Background service hosts<br/>platform service"]
end

node_runtime_config -->|"configures"| node_opencode
node_repo_rules -->|"governs"| node_opencode
node_architecture_rules -->|"instructs"| node_opencode
node_identity -->|"sets priority rules"| node_opencode
node_opencode -->|"runs"| node_orchestrator
node_orchestrator -->|"delegates execution"| node_implementer
node_orchestrator -->|"sends for review"| node_reviewer
node_orchestrator -->|"isolates parallel work"| node_gjc_delegate
node_opencode -->|"selects workflows"| node_skills
node_opencode -->|"uses"| node_knowledge_plugin
node_memory_tools -->|"reads and writes"| node_knowledge_plugin
node_scheduler -->|"loads"| node_cron_jobs
node_scheduler -->|"triggers agent work"| node_opencode
node_kanban_worker -->|"dispatches staged work"| node_orchestrator
node_discord_gateway -->|"creates sessions"| node_opencode
node_environment -->|"provides bot token"| node_discord_gateway
node_runtime_config -.->|"registers boundary"| node_knowledge_plugin
node_service_hosts -->|"keeps running"| node_scheduler

click node_runtime_config "https://github.com/humanerd-drew/opencode-drewgent/blob/main/opencode.jsonc"
click node_repo_rules "https://github.com/humanerd-drew/opencode-drewgent/blob/main/AGENTS.md"
click node_architecture_rules "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/instructions/00-architecture.md"
click node_identity "https://github.com/humanerd-drew/opencode-drewgent/blob/main/%40identity/brain/rules.md"
click node_orchestrator "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/orchestrator.md"
click node_implementer "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/implementer.md"
click node_reviewer "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/reviewer.md"
click node_gjc_delegate "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/tools/delegate.ts"
click node_knowledge_plugin "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/plugins/knowledge.js"
click node_memory_tools "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/tools/remember.ts"
click node_cron_jobs "https://github.com/humanerd-drew/opencode-drewgent/blob/main/cron/jobs.json"
click node_scheduler "https://github.com/humanerd-drew/opencode-drewgent/blob/main/cron/scheduler.py"
click node_kanban_worker "https://github.com/humanerd-drew/opencode-drewgent/blob/main/scripts/run_kanban_worker.py"
click node_discord_gateway "https://github.com/humanerd-drew/opencode-drewgent/blob/main/scripts/discord_bot.py"
click node_environment "https://github.com/humanerd-drew/opencode-drewgent/blob/main/.env.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime_config,node_repo_rules,node_architecture_rules,node_identity toneBlue
class node_orchestrator,node_implementer,node_reviewer,node_gjc_delegate toneAmber
class node_knowledge_plugin,node_memory_tools,node_skills toneMint
class node_cron_jobs,node_scheduler,node_kanban_worker toneRose
class node_opencode,node_discord_gateway,node_environment,node_service_hosts toneIndigo
```

## Components

### Governance

- [Runtime integration](https://github.com/humanerd-drew/opencode-drewgent/blob/main/opencode.jsonc): JSONC config · Configures opencode and MCP integration boundaries. · `opencode.jsonc`
- [Repository rules](https://github.com/humanerd-drew/opencode-drewgent/blob/main/AGENTS.md): operating guidance · `AGENTS.md`
- [Architecture instructions](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/instructions/00-architecture.md): instruction · `.opencode/instructions/00-architecture.md`
- [Identity hierarchy](https://github.com/humanerd-drew/opencode-drewgent/blob/main/%40identity/brain/rules.md): durable identity · Rules override persona and self-model preferences. · `@identity/brain/rules.md`

### Agent Control

- [Orchestrator profile](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/orchestrator.md): agent profile · Selects specialists and directs work stages. · `.opencode/agents/orchestrator.md`
- [Implementer profile](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/implementer.md): editing specialist · `.opencode/agents/implementer.md`
- [Reviewer profile](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/agents/reviewer.md): quality specialist · Read-only quality gate for delegated work. · `.opencode/agents/reviewer.md`
- [GJC delegation](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/tools/delegate.ts): parallel work tool · Routes isolated work through worktree/tmux coordination. · `.opencode/tools/delegate.ts`

### Knowledge & Skills

- [Knowledge service](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/plugins/knowledge.js): opencode plugin · Filesystem-backed memory operations and graph retrieval. · `.opencode/plugins/knowledge.js`
- [Remember / recall](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.opencode/tools/remember.ts): knowledge tools · Writes reusable facts and retrieves provenance. · `.opencode/tools/remember.ts`
- **Skill catalog**: on-demand workflows · Skill instructions select capabilities and supporting resources.

### Automation & Work

- [Scheduled jobs](https://github.com/humanerd-drew/opencode-drewgent/blob/main/cron/jobs.json): job definitions · `cron/jobs.json`
- [Cron scheduler](https://github.com/humanerd-drew/opencode-drewgent/blob/main/cron/scheduler.py): Python scheduler · Loads and executes configured scheduled work. · `cron/scheduler.py`
- [Kanban worker](https://github.com/humanerd-drew/opencode-drewgent/blob/main/scripts/run_kanban_worker.py): work runner · Persists and advances work across explorer, implementer, and reviewer stages. · `scripts/run_kanban_worker.py`

### Interfaces & Runtime

- **opencode runtime**: agent runtime · Primary interactive agent entry point.
- [Discord gateway](https://github.com/humanerd-drew/opencode-drewgent/blob/main/scripts/discord_bot.py): bot gateway · Maps Discord threads to persistent opencode sessions and streams activity. · `scripts/discord_bot.py`
- [Environment secrets](https://github.com/humanerd-drew/opencode-drewgent/blob/main/.env.example): environment config · Supplies tokens and external service configuration. · `.env.example`
- **Background service hosts**: platform service · Launchd, systemd, and Windows scheduled-task deployment options.

## Connections

- Runtime integration → opencode runtime: configures
- Repository rules → opencode runtime: governs
- Architecture instructions → opencode runtime: instructs
- Identity hierarchy → opencode runtime: sets priority rules
- opencode runtime → Orchestrator profile: runs
- Orchestrator profile → Implementer profile: delegates execution
- Orchestrator profile → Reviewer profile: sends for review
- Orchestrator profile → GJC delegation: isolates parallel work
- opencode runtime → Skill catalog: selects workflows
- opencode runtime → Knowledge service: uses
- Remember / recall → Knowledge service: reads and writes
- Cron scheduler → Scheduled jobs: loads
- Cron scheduler → opencode runtime: triggers agent work
- Kanban worker → Orchestrator profile: dispatches staged work
- Discord gateway → opencode runtime: creates sessions
- Environment secrets → Discord gateway: provides bot token
- Runtime integration → Knowledge service: registers boundary
- Background service hosts → Cron scheduler: keeps running