# https://github.com/gptme/gptme-agent-template Project Manual Generated at: 2026-06-13 16:25:37 UTC ## Table of Contents - [Introduction to the gptme-agent-template](#page-1) - [Workspace Architecture, Tasks, and State Management](#page-2) - [Autonomous Operation, Multi-Backend Support, and Infrastructure](#page-3) - [Forking, Customization, and Domain Agent Apps](#page-4) ## Introduction to the gptme-agent-template ### Related Pages Related topics: [Workspace Architecture, Tasks, and State Management](#page-2), [Forking, Customization, and Domain Agent Apps](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md) - [ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md) - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) - [AGENTS.md](https://github.com/gptme/gptme-agent-template/blob/main/AGENTS.md) - [CLAUDE.md](https://github.com/gptme/gptme-agent-template/blob/main/CLAUDE.md) - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) - [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md) - [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md) - [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md) - [projects/README.md](https://github.com/gptme/gptme-agent-template/blob/main/projects/README.md)
# Introduction to the gptme-agent-template ## Purpose and Scope The `gptme-agent-template` is a scaffold for building [gptme](https://gptme.org)-based autonomous agents. As stated in [README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md), "This is a template for a gptme-based agent" intended to be forked into a new repository that becomes the agent's persistent workspace, identity store, and memory system. The template itself ships under the default agent name `gptme-agent` and serves as both a working example and the canonical starting point. The repository acts as the agent's "brain": a versioned workspace of thoughts, tasks, journals, people profiles, and knowledge ([README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md)). Each fork inherits the same harness while gaining its own personality, goals, and accumulated experience. ### Key Capabilities - **Identity management** via [`ABOUT.md`](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md) and `SOUL.md` - **Task tracking** through [`TASKS.md`](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) and the `gptodo` CLI - **Journaling** under [`./journal/`](https://github.com/gptme/gptme-agent-template/blob/main/README.md) - **Context generation** through [`./scripts/context.sh`](https://github.com/gptme/gptme-agent-template/blob/main/README.md) - **Behavioral lessons** stored in [`./lessons/`](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md) ## High-Level Architecture The template is composed of layered content scopes and runtime contracts that work together to produce a working agent. ```mermaid flowchart TB subgraph Template["Agent Template (this repo)"] Identity[ABOUT.md / SOUL.md] Tasks[TASKS.md + tasks/] Journal[journal/] Knowledge[knowledge/] Lessons[lessons/] Scripts[scripts/context.sh] Workflow[WORKFLOW.md] end subgraph Contrib["gptme-contrib (submodule)"] Hooks[pre-commit hooks] SharedScripts[shared scripts] Pkgs[packages / plugins] end subgraph Runtime["Agent Runtime"] Gptme[gptme] ClaudeCode[Claude Code / Codex] end Identity --> Runtime Tasks --> Runtime Scripts --> Runtime Workflow --> Runtime Template -.symlinks.-> Contrib Runtime --> Journal Runtime --> Knowledge ``` The figure shows three concerns: identity and memory files in the template, shared assets pulled in from the `gptme-contrib` submodule, and the runtime harness that consumes the contract. ## Content Layers A critical architectural concept documented in [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) is the layered nature of agent workspaces. Each layer has a distinct scope and update cadence. | Layer | Repository | Scope | Typical Content | |-------|------------|-------|-----------------| | Agent template | `gptme-agent-template` | All agents | Workspace structure, scripts, configs, templates | | Public shared | `gptme-contrib` | All gptme users | Packages, plugins, lessons, pre-commit hooks | | Org shared | (e.g. `gptme-superuser`) | Org agents | Strategy, people, operations, processes | | Agent workspace | (this fork) | Single agent | Identity, journals, tasks, knowledge | The rule of thumb from the architecture documentation: "if the content is generic and useful across agents, it should live in contrib with the template symlinking to it. If it's workspace structure or identity, it lives in the template directly" ([ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)). This separation keeps generic assets reusable while preserving agent-specific identity. ## Workspace Structure The template organizes agent state into well-defined directories, each with a clear responsibility: - **`state/`** — Work queue management with `queue-manual.md` and `queue-generated.md`, following a two-queue system ([README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md)). - **`scripts/`** — Automation and utilities, including `context.sh` (main context orchestrator) and `gptodo` (task management CLI from `gptme-contrib`). - **`lessons/`** — Behavioral patterns that prevent known failure modes, documented in [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md). - **`knowledge/`** — Long-form technical designs, forking guides, and reusable patterns (e.g. `knowledge/forking-workspace.md`, `knowledge/portable-agent-apps.md`). - **`people/`** — Profiles of collaborators and contacts the agent interacts with. - **`projects/`** — Symlinks to projects the agent works on, as described in [projects/README.md](https://github.com/gptme/gptme-agent-template/blob/main/projects/README.md). The journal follows a date-based layout (`journal/YYYY-MM-DD/`) and uses templates to ensure consistent entries — a convention introduced in v0.3 ([release notes](https://github.com/gptme/gptme-agent-template/releases/tag/v0.3)). ## Forking and Identity Forking the template is the canonical way to create a new agent. Two paths are supported per [README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md): 1. **Programmatic:** `gptme-agent create ` 2. **Manual:** clone the repo, initialize submodules, and run `./scripts/fork.sh []` The forking process is guided by [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md), which specifies what to copy (structure, configs), what to clear (personal content, identity files, people profiles), and how to initialize a new identity. After the fork, `ABOUT.md` is customized with the agent's personality, tools, goals, and values ([ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md)), while `SOUL.md` carries the runtime persona. ## Runtime Contracts The template supports multiple agent runtimes through shared instruction files. [AGENTS.md](https://github.com/gptme/gptme-agent-template/blob/main/AGENTS.md) and [CLAUDE.md](https://github.com/gptme/gptme-agent-template/blob/main/CLAUDE.md) define identical core rules — file operations with absolute paths, conventional commit style, the default `master` branch, and pre-commit hook expectations. The runtimes differ in how they load identity: - **gptme** auto-loads identity files via `gptme.toml` and runs `scripts/context.sh` dynamically ([CLAUDE.md](https://github.com/gptme/gptme-agent-template/blob/main/CLAUDE.md)). - **Claude Code / Codex** auto-loads only the instruction file; agents must manually read bootstrap files (`ABOUT.md`, `ARCHITECTURE.md`, `TASKS.md`) and invoke `scripts/context.sh` themselves. For autonomous operation, [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) provides a repo-versioned workflow contract with YAML front-matter for runtime configuration and Markdown body for instructions. Placeholders like `{{WORKSPACE}}`, `{{DATE}}`, and `{{SESSION_HASH}}` are injected at run time by `scripts/workflow-render.py`. ## Common Failure Modes and Lessons The [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md) documentation emphasizes that lessons use a two-file format: a concise primary file (30–50 lines) plus an optional companion in `knowledge/lessons/` for deep context. Keywords must be precise multi-word phrases — single generic words like `git` or `python` pollute the context window and should be avoided. Known portability pitfalls are catalogued in [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md), which warns against "fork traps": apps that cannot state what survives an update. The **Update Preservation Rule** requires every reusable app to (1) mark generated files, (2) keep user-owned files out of generated paths, (3) preserve `tasks/`, `journal/`, secrets, and profiles, (4) detect drift before overwriting, and (5) run validation after every update. ## See Also - [gptme Documentation](https://gptme.org/docs/agents.html) — Background on gptme agents - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) — Detailed system design - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) — Autonomous workflow contract - [Release Notes v0.4](https://github.com/gptme/gptme-agent-template/releases/tag/v0.4) — Latest template updates --- ## Workspace Architecture, Tasks, and State Management ### Related Pages Related topics: [Introduction to the gptme-agent-template](#page-1), [Autonomous Operation, Multi-Backend Support, and Infrastructure](#page-3)
Related Source Files The following source files were used to generate this page: - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) - [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) - [ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md) - [state/queue-manual.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-manual.md) - [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md) - [journal/templates/daily.md](https://github.com/gptme/gptme-agent-template/blob/main/journal/templates/daily.md) - [people/templates/person.md](https://github.com/gptme/gptme-agent-template/blob/main/people/templates/person.md) - [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md)
# Workspace Architecture, Tasks, and State Management ## Overview The `gptme-agent-template` repository provides a forkable agent workspace structure used as the foundation for autonomous AI agents built with [gptme](https://github.com/gptme/gptme). The workspace combines a layered content model, a task-tracking system, journal logging, a knowledge base, a people directory, and a session-level state machine for autonomous runs. According to [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md), the design goal is to keep identity, work, and long-term knowledge cleanly separated so the template can be forked and customized for new agents without losing shared best practices. The workspace is intentionally "repo-versioned": every long-lived artifact (tasks, journal entries, knowledge articles, queue state) lives as a Markdown file in the repository, making changes diffable, reviewable, and recoverable. The release notes for v0.3 highlight the move toward a simplified task directory and a CI workflow, which is why tasks now live directly under `tasks/` rather than under `CURRENT_TASK.md` or `tasks/all/` as in earlier revisions. ## Workspace Architecture and Content Layers The repository is organized into several content layers with different scopes and update cadences. [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) defines four layers; the table below summarizes how each contributes to the workspace. | Layer | Source | Scope | Typical Content | |-------|--------|-------|-----------------| | Agent template | `gptme-agent-template` | All agents | Workspace structure, scripts, configs, templates | | Public shared | `gptme-contrib` | All gptme users | Packages, plugins, lessons, pre-commit hooks | | Org shared | e.g. `gptme-superuser` | Org agents | Strategy, people, operations, processes | | Agent workspace | (this repo) | Single agent | Identity, journals, tasks, knowledge | The template uses git submodules so that shared content can be updated by pulling a new submodule pointer rather than rewriting files locally. Most files in the template are symlinks into `gptme-contrib`, while agent-specific files such as `ABOUT.md`, `SOUL.md`, `gptme.toml`, and `README.md` are kept under local control. Source: [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md). Beyond content layers, the workspace has five functional areas: - **Tasks** — single-source-of-truth work items under [`tasks/`](https://github.com/gptme/gptme-agent-template/tree/main/tasks), validated by pre-commit hooks. - **Journal** — append-only daily logs under `journal/YYYY-MM-DD/HHMMSS-topic.md` capturing progress, decisions, and reflections. - **Knowledge base** — long-term reference material under [`knowledge/`](https://github.com/gptme/gptme-agent-template/tree/main/knowledge), including forking instructions and tooling guides. - **People directory** — stable profiles under [`people/`](https://github.com/gptme/gptme-agent-template/tree/main/people) for collaborators the agent interacts with. - **State** — runtime queue and tracker files under [`state/`](https://github.com/gptme/gptme-agent-template/tree/main/state) consumed by autonomous-runner scripts. Each functional area is documented in its own file: [`TASKS.md`](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md), [`journal/templates/daily.md`](https://github.com/gptme/gptme-agent-template/blob/main/journal/templates/daily.md), and [`people/templates/person.md`](https://github.com/gptme/gptme-agent-template/blob/main/people/templates/person.md) all ship templates that define the schema and expected sections for their respective content types. ## Task System The task system tracks work across sessions using YAML-frontmatter Markdown files. Each task carries an identifier (slug), a `state`, a `created` timestamp, optional `priority`, `tags`, and `depends` fields, followed by a Markdown body describing the work. Source: [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md). Tasks move through five lifecycle stages: 1. **Creation** — author a new file in `tasks/` with frontmatter and body. 2. **Activation** — set `state: active` in the frontmatter and announce it in a journal entry. 3. **Progress tracking** — record updates in journal entries and tick subtasks. 4. **Completion/cancellation** — set `state: done` or `state: cancelled` with a final journal entry. 5. **Pausing** — set `state: paused`, document progress, and capture the reason. The `gptodo` CLI (installed from `gptme-contrib`) is the canonical interface for listing, showing, and editing tasks without hand-editing frontmatter. Common commands documented in [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) include `gptodo status`, `gptodo list`, `gptodo show `, and `gptodo edit --set state active`. Pre-commit hooks validate metadata format and values, ensuring that downstream tools can trust the fields. The v0.3 release notes confirm the task directory was simplified (no more `CURRENT_TASK.md` or `tasks/all/`) and CI was added to enforce these checks. ## State Management and Autonomous Workflow Runtime state for an autonomous agent lives under [`state/`](https://github.com/gptme/gptme-agent-template/tree/main/state) and is driven by [`WORKFLOW.md`](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md), a repo-versioned contract consisting of YAML front matter (configuration) and a Markdown body (instructions with `{{PLACEHOLDER}}` substitution). Source: [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). Two queue files orchestrate which work is picked up next: - **`state/queue-manual.md`** — the *primary* source. Maintained by the agent or operator, containing session reasoning, dependencies, and strategic notes for the next planned work items. Source: [state/queue-manual.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-manual.md). - **`state/queue-generated.md`** — the *fallback* source. Auto-generated from `tasks/` and GitHub issues to provide objective, fresh priorities when the manual queue is empty. Source: [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md). The WORKFLOW front matter defines `harness` (allowed runtimes such as `gptme` and `claude-code`), `tracker` (currently `gptodo` with `tasks_dir`), `session` defaults (timeout, commit style, pre-commit requirement), and `context.prebuilt` (always-loaded files such as `README.md`, `ABOUT.md`, `SOUL.md`, `ARCHITECTURE.md`, and `TASKS.md`). Dynamic context is built by `scripts/context.sh`. Source: [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). A typical autonomous session follows four phases, as documented in the workflow body: (1) **Setup** — refresh the workspace and load context; (2) **Planning** — pick work from the manual queue or generated fallback, run `make typecheck` and `make test`; (3) **Execution** — make commits using conventional commit messages and update task state when complete; (4) **Completion** — log progress under `journal/{{DATE}}/autonomous-session-{{SESSION_HASH}}.md`, commit, and `git push origin HEAD`. The four-phase loop is invoked by runner scripts such as `scripts/runs/autonomous/` described in the autonomous-run README. ## See Also - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) — overall workspace design and content layers. - [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) — task frontmatter schema, lifecycle, and `gptodo` reference. - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) — runtime contract for autonomous sessions. - [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md) — how to fork the template into a new agent. - [Release v0.3](https://github.com/gptme/gptme-agent-template/releases/tag/v0.3) — note on simplified task structure and added CI. --- ## Autonomous Operation, Multi-Backend Support, and Infrastructure ### Related Pages Related topics: [Workspace Architecture, Tasks, and State Management](#page-2), [Forking, Customization, and Domain Agent Apps](#page-4)
Related Source Files The following source files were used to generate this page: - [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md) - [scripts/runs/autonomous/autonomous-run.sh](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/autonomous-run.sh) - [scripts/runs/autonomous/autonomous-run-cc.sh](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/autonomous-run-cc.sh) - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) - [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md) - [dotfiles/.config/systemd/user/agent-autonomous.service.example](https://github.com/gptme/gptme-agent-template/blob/main/dotfiles/.config/systemd/user/agent-autonomous.service.example) - [dotfiles/.config/systemd/user/agent-autonomous.timer.example](https://github.com/gptme/gptme-agent-template/blob/main/dotfiles/.config/systemd/user/agent-autonomous.timer.example) - [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md) - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) - [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)
# Autonomous Operation, Multi-Backend Support, and Infrastructure ## Overview The `gptme-agent-template` ships a self-contained infrastructure for running an agent **autonomously on a schedule**, while remaining **agent-harness agnostic**. Two parallel entry points — `autonomous-run.sh` for `gptme` and `autonomous-run-cc.sh` for Claude Code — execute the same CASCADE workflow contract declared in [`WORKFLOW.md`](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md), and are wired into a systemd user timer for unattended operation. Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md). This design decouples three concerns that are normally tangled in autonomous agents: | Concern | Owner | |--------|-------| | Workflow contract | `WORKFLOW.md` (YAML front matter + Markdown body) | | Harness execution | `autonomous-run.sh`, `autonomous-run-cc.sh` | | Scheduling & lifecycle | systemd user timer + service unit | ## Architecture ```mermaid flowchart LR Timer["systemd timer
(agent-autonomous.timer)"] Service["systemd service
(agent-autonomous.service)"] Script["autonomous-run.sh
or autonomous-run-cc.sh"] Contract["WORKFLOW.md
(contract)"] Queue["state/queue-manual.md
fallback: queue-generated.md"] Tasks["tasks/*.md"] Journal["journal/YYYY-MM-DD/"] Git["git push origin HEAD"] Timer -->|OnCalendar| Service Service -->|ExecStart| Script Script -->|reads| Contract Script -->|reads| Queue Queue -.->|refreshed from| Tasks Script -->|writes| Journal Script -->|commits &| Git ``` Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md), [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). ## The CASCADE Workflow Contract `WORKFLOW.md` is the **repo-versioned contract** between the harness and the agent. Its YAML front matter is consumed by `scripts/workflow-render.py` at runtime, while the Markdown body carries the agent instructions. Source: [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). The front matter declares: - `harness.allowed` — the list of supported runtimes, defaulting to `gptme` and including `claude-code`. Source: [WORKFLOW.md:1-15](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). - `tracker.kind` — the task system in use (`gptodo`). - `session.default_timeout` — wall-clock cap per run (45 minutes by default). - `session.commit_style` — `conventional` commits enforced via `require_precommit`. - `hooks.post_commit` — automatic `git push origin HEAD` after each successful commit. - `context.prebuilt` and `context.dynamic_cmd` — the set of files always preloaded into the model context, plus a shell command that injects dynamic context before each run. The Markdown body defines four phases — **Loose Ends → Task Selection → Execution → Completion** — and explicitly states that "there is always Tier 3 work available", discouraging empty NOOP sessions. Source: [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md). ## Multi-Backend Harness Support Multi-backend support is implemented as **two parallel shell scripts** rather than a single script with branches: | Script | Backend | Notes | |--------|---------|-------| | `scripts/runs/autonomous/autonomous-run.sh` | `gptme` | Original runbook, used by the default service unit. | | `scripts/runs/autonomous/autonomous-run-cc.sh` | Claude Code | Parallel implementation; requires a separate `agent-autonomous-cc.service` unit. | Both scripts implement the same CASCADE phases and read the same `WORKFLOW.md` contract; only the final `gptme` / `claude-code` invocation differs. This keeps each backend's quirks (argument shape, tool-call protocol) localized to one file. Source: [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md). The `harness.allowed` list in `WORKFLOW.md` is the single source of truth for which backends are valid; forks should add new harnesses there and ship a matching `autonomous-run-.sh` plus a `*.service.example` unit. ## Scheduling with systemd The template ships example unit files in `dotfiles/.config/systemd/user/`: - `agent-autonomous.service.example` — runs `autonomous-run.sh` once per activation. - `agent-autonomous.timer.example` — triggers the service on a `OnCalendar` schedule. - `agent-autonomous-cc.service.example` — Claude Code counterpart. The README notes the default schedule is **hourly**, with common variants being every 15 minutes (`*:0/15`) or three times a day (`*-*-* 06,10,14:00:00`). Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md). Operators inspect state with: ```bash systemctl --user status agent-autonomous.timer journalctl --user -u agent-autonomous.service --since "1 hour ago" journalctl --user -u agent-autonomous.service -f ``` Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md). ## Queue System & Task Selection The autonomous run resolves its next action through a **two-queue priority scheme**: 1. **`state/queue-manual.md`** — PRIMARY source. Manually curated, contains rich session reasoning, dependencies, and strategic notes. If populated, it overrides everything. 2. **`state/queue-generated.md`** — FALLBACK source. Auto-generated from `tasks/*.md` and open GitHub issues before each run. The template for this file is a plain Markdown stub that lists a "Current Run" header and a "Planned Next" section. Source: [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md). Tasks themselves live directly under `tasks/` as individual Markdown files with YAML frontmatter (`state`, `created`, `priority`, `tags`, `depends`). A pre-commit hook validates the metadata, and the `gptodo` CLI surfaces them via `gptodo status`, `gptodo list --sort state`, etc. Source: [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md). ## Safety Classifications The autonomous-run script tags each operation class with a traffic light so the agent (or its operator) can decide without re-deriving policy: - **GREEN** — code, tests, docs, refactoring: execute autonomously. - **YELLOW** — social media, email: follow established patterns. - **RED** — financial, major decisions: escalate to a human. These classifications are intentionally templated and **must be customized per fork** to reflect the operator's risk tolerance. Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md). ## Common Failure Modes The README enumerates the three most frequent breakages: 1. **Script exits immediately** — usually a missing `WORKSPACE` path or `gptme` not on `PATH`. 2. **`git pull` fails** — SSH keys not loaded for the systemd user, or no network. 3. **Timeouts** — `SCRIPT_TIMEOUT` is too short for the chosen schedule; the README recommends 3000s for hourly runs and 6000s for every-two-hour runs. Source: [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md). Additional failure surfaces referenced by `WORKFLOW.md`: - **Pre-commit regressions** — `require_precommit: true` causes the run to abort if `make typecheck` / `make test` fail; agents must fix regressions, not bypass hooks. - **Template drift** — agents forked from this template will diverge as the template evolves; the v0.2 release notes emphasize running template-comparison checks before each run. Source: [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md). ## Customization Checklist Before going live on a fork, the README and `WORKFLOW.md` front matter recommend adjusting: - `harness.default` and per-harness `model_routing` in `WORKFLOW.md`. - The timer's `OnCalendar` and `SCRIPT_TIMEOUT`. - Pre-run validation hooks (e.g. `scripts/validate-workspace.sh`). - Safety classifications to match your domain. - Manual queue content — an empty `queue-manual.md` will silently fall through to auto-generation. ## See Also - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) — overall workspace architecture and content layers. - [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) — task lifecycle, metadata, and `gptodo` CLI reference. - [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md) — full script catalog including journal migration and search utilities. - [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md) — fork hygiene so template updates land cleanly. --- ## Forking, Customization, and Domain Agent Apps ### Related Pages Related topics: [Introduction to the gptme-agent-template](#page-1), [Autonomous Operation, Multi-Backend Support, and Infrastructure](#page-3)
Related Source Files The following source files were used to generate this page: - [knowledge/agent-forking.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/agent-forking.md) - [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md) - [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md) - [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) - [ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md) - [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) - [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) - [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md) - [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md)
# Forking, Customization, and Domain Agent Apps ## Overview and Purpose The `gptme-agent-template` is designed as a **forkable agent architecture**: a foundation for creating new agents that share a robust infrastructure while developing their own identity, goals, and workflows. Forking is the primary mechanism for distributing the template, and v0.2 specifically called out "improved forking" and "more pre-commit checks to make sure new forks are good" as release highlights ([v0.2 release](https://github.com/gptme/gptme-agent-template/releases/tag/v0.2)). The template is intentionally split into three concerns that the forking process must respect: 1. **Forking** — the mechanical act of copying the workspace and resetting identity-bearing content. 2. **Customization** — the design of *what* should be customized (identity, tasks, journals) versus *what* must remain generic (architecture, tools, content layers). 3. **Domain Agent Apps** — a higher-level concept of packaging a workflow as a reusable app with a single source of truth for the workflow, separated into system and user layers. `Source: [knowledge/agent-forking.md:1-14]()` ## Forking an Agent ### The Forking Concept Forking in this template is **not a one-shot code fork on GitHub**. It is a workspace copy operation in which the new repository inherits the template's directory structure, scripts, configurations, and documentation templates, but starts fresh on personal, identity-bearing state. The original template repository (`gptme-agent-template`) is treated as a parent that new agents can sync updates from. `Source: [knowledge/agent-forking.md:1-14]()` ### What Stays and What Gets Cleared The forking process distinguishes carefully between content that defines the system and content that defines the individual agent. The table below summarizes the policy described in the template's forking documentation. | Category | Preserved | Cleared | |----------|-----------|---------| | Structure | Directory layout, task management, documentation templates, tool configurations | — | | Core docs | `ARCHITECTURE.md`, `TOOLS.md`, technical designs, integration guides | — | | Identity | — | `ABOUT.md`, visual identity, social media presence, personal profile | | Personal content | — | Journal entries, task bodies, project links, agent-specific knowledge | | People directory | Creator profile, profile templates | Other people profiles and interaction history | | Knowledge | Generic AI/ML concepts, system architecture, tool usage patterns | Domain-specific knowledge evaluated per-file | `Source: [knowledge/forking-workspace.md:13-60]()` ### Fork Creation Steps The documented procedure is intentionally simple: 1. Copy the workspace structure. 2. Clear personal content as described above. 3. Initialize a new identity (name, personality, goals, visual identity, social presence). 4. Update configurations (paths in `gptme.toml`, `ABOUT.md`, etc.). 5. Create the first task to give the agent a starting direction. `Source: [knowledge/forking-workspace.md:42-49]()` For a customization checklist after the copy, the forking guide recommends defining identity (personality, communication style, boundaries, visual identity), purpose (goals, focus areas, success metrics), and relationships (creator, peers, boundaries). `Source: [knowledge/agent-forking.md:17-40]()` ## Customization and Content Layers The template composes shared content via git submodules. Each layer has a different scope, and the forking process must respect these boundaries to prevent duplication and staleness. ```mermaid graph TD T["gptme-agent-template
(All agents)"] -->|symlinks| C["gptme-contrib
(All gptme users)"] T -->|copy+fork| W["Agent workspace
(Single agent)"] O["Org-shared repo
(e.g. gptme-superuser)"] -->|submodule| W C -.->|updates| T O -.->|updates| W ``` The relationship between the **template** and **contrib** repos is critical: most files in the agent template should be **symlinks into `gptme-contrib`** so that agents pick up updates by simply updating the contrib submodule. Examples include pre-commit hooks, lesson files, shared scripts, and validators. Some files **cannot be symlinks** because they are agent-specific or require local customization: `ABOUT.md`, `SOUL.md`, `gptme.toml`, `README.md`, and task/journal content. The rule of thumb stated in the architecture doc is: *if the content is generic and useful across agents, it should live in contrib with the template symlinking to it; if it is workspace structure or identity, it lives in the template directly.* `Source: [ARCHITECTURE.md:54-77]()` Forked agents will drift from the template over time. The architecture document recommends adding the template as a remote and diffing against it to detect new shared content that should be pulled in. `Source: [ARCHITECTURE.md:78-83]()` ### Task System Customization The task system was simplified in v0.3 to remove `CURRENT_TASK.md` and the `tasks/all/` directory; tasks are now stored directly under `tasks/` and validated by pre-commit hooks ([v0.3 release](https://github.com/gptme/gptme-agent-template/releases/tag/v0.3)). The optional `gptodo` CLI, installed from `gptme-contrib`, provides status, list, show, and edit operations. Task files use YAML frontmatter for `state`, `created`, `priority`, `tags`, and `depends` fields, and follow a lifecycle of creation → activation → progress tracking → completion/pause. `Source: [TASKS.md:1-90]()` ## Domain Agent Apps (Portable Apps) The template extends the forking concept with a higher-level abstraction: **portable agent apps**. An app is a repository that packages a domain workflow for an agent to operate — "more than a prompt and less than a bespoke runtime." Examples include a release manager, support triage operator, research assistant, personal finance operator, or self-monitoring agent. `Source: [knowledge/portable-agent-apps.md:1-16]()` ### The Core Rule: One Source of Truth The core rule is **keep workflow truth in one place**. Runtime-specific files (`AGENTS.md`, `WORKFLOW.md`, skill wrappers, foreign runtime exports) may point to that workflow, wrap it, or expose it through a schema, but they must not copy the workflow body by hand. The doc is explicit: *"If two files repeat the same domain procedure in full, one of them is already rotting."* `Source: [knowledge/portable-agent-apps.md:18-23]()` ### System Layer vs. User Layer Before adding features, the app should be split into two layers: - **System layer** (upgradeable product surface): runtime entrypoints, commands, bundles, skills, shared procedures, scripts, templates, validators, and generated compatibility exports. - **User layer** (private or identity-bearing state): profiles, preferences, local policy, tasks, journals, generated reports, run history, credentials, and long-lived local data stores. System updates may replace or regenerate system-layer files; they must preserve user-layer files by default. `Source: [knowledge/portable-agent-apps.md:25-45]()` ### Update Preservation Rule Every reusable app needs an explicit update rule: 1. Mark generated files with their source or exporter. 2. Keep user-owned files out of generated paths. 3. Preserve `tasks/`, `journal/`, secrets, and local profiles by default. 4. Detect drift before overwriting user-edited system files. 5. Run validation after every update. The doc states bluntly: *"If an app cannot say what survives an update, it is a fork trap."* `Source: [knowledge/portable-agent-apps.md:65-72]()` ## Common Pitfalls and Best Practices - **Over-copying workflow content.** Duplicating a checklist in `AGENTS.md`, a skill, and a foreign runtime export leads to rot. Route all of them to a single `commands/.md` owner. - **Losing template updates by editing symlinked files.** Files that are symlinks into `gptme-contrib` will be overwritten by the next submodule update. Local customization belongs in non-symlinked files. - **Clearing too much during a fork.** Stripping the knowledge base wholesale removes generic AI/ML content that should remain. Evaluate files individually rather than wiping directories. - **Forgetting pre-commit validation.** v0.2 added pre-commit checks specifically to ensure new forks are good; failing to run them can produce a fork that drifts from the template's quality bar. - **Skipping the update preservation rule on a portable app.** Without it, the app becomes a one-shot fork that cannot receive system-layer improvements without losing user state. `Source: [knowledge/forking-workspace.md:13-60](), [knowledge/portable-agent-apps.md:18-72](), [v0.2 release notes](https://github.com/gptme/gptme-agent-template/releases/tag/v0.2)` ## See Also - [Workspace Architecture](./architecture.md) - [Task Management System](./tasks.md) - [Lesson System](./lessons.md) - [Autonomous Run Infrastructure](./autonomous-runs.md) --- --- ## Pitfall Log Project: gptme/gptme-agent-template Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification. ## 1. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 2. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 3. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 6. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template ## 7. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template