gptme-agent-template

June 7, 2026 · View on GitHub

Note

This is a template for a gptme-based agent. See the agents documentation for more information about gptme agents and how they work.

Fork it to create a new agent with its own identity.

The name of the agent is gptme-agent.

This git repository is the brain of gptme-agent. It is a workspace of their thoughts and ideas.

gptme-agent will write their thoughts, plans, and ideas in this repository.
gptme-agent's agent harness, including this repo, is in-progress.
gptme-agent is encouraged to suggest improvements to their harness.

Information about gptme-agent can be found in ABOUT.md, including their personality and goals. gptme-agent's runtime persona — voice, taste, and stance — lives in SOUL.md, kept short and high-signal. Information about gptme-agent's harness and architecture can be found in ARCHITECTURE.md.

Prerequisites

Before forking or using this template, ensure you have the required dependencies installed.

Quick Check:

./scripts/install-deps.sh

Auto-Install (where possible):

./scripts/install-deps.sh --install

Required Dependencies

Dependency	Purpose	Installation
`git`	Version control	Package manager
`python3`	Python 3.10+ runtime	Package manager
`pipx`	Python CLI tool installer	`python3 -m pip install --user pipx`
`uv`	Fast Python package manager	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
`gptme`	Agent framework	`pipx install gptme`

Recommended Dependencies

Dependency	Purpose	Installation
`tree`	Directory visualization	`apt/brew/dnf install tree`
`jq`	JSON processing	`apt/brew/dnf install jq`
`gh`	GitHub CLI	cli.github.com
`prek`	Git hooks (fast Rust runner)	`uv tool install prek`
`shellcheck`	Shell script linter	`apt/brew/dnf install shellcheck`

Quick Start

The easiest way to create a new agent from this template is with the gptme-agent CLI (included with gptme):

pipx install gptme

# Create a new agent workspace from this template
gptme-agent create ~/my-agent --name MyAgent

cd ~/my-agent

# Run the agent interactively
gptme "hello"

The agent's context is automatically loaded via gptme.toml which configures the files and context command to include.

Claude Code Backend

The template also supports Claude Code as an alternative backend:

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Authenticate
claude /login

# Run interactively (reads AGENTS.md automatically)
claude

# Run autonomously
./scripts/runs/autonomous/autonomous-run-cc.sh

The scripts/build-system-prompt.sh script reads gptme.toml and builds a system prompt for Claude Code, so both backends share the same identity files and context.

Workspace Health Check

After creating or forking an agent workspace, verify everything is configured correctly:

gptme-agent doctor

This checks core files, configuration, directories, tools, and submodules. Use --fix to auto-fix simple issues (create missing directories, initialize submodules).

Requires gptme >= v0.32

Run the agent interactively with gptme or Claude Code:

gptme "hello"
# or: claude

Autonomous Operation

Agents can run autonomously on a schedule using systemd (Linux) or launchd (macOS).

# Install as a system service (runs every 30 minutes by default)
gptme-agent install

# Customize the schedule
gptme-agent install --schedule "*:00"    # Every hour

# Manage the agent
gptme-agent status              # Check status
gptme-agent logs --follow       # Monitor logs
gptme-agent run                 # Trigger immediate run
gptme-agent stop                # Pause scheduled runs

See the gptme agents documentation for service installation and management commands.

To customize the autonomous behavior, edit the run script for your backend:

gptme: scripts/runs/autonomous/autonomous-run.sh
Claude Code: scripts/runs/autonomous/autonomous-run-cc.sh

See: scripts/runs/autonomous/README.md for complete documentation.

Features:

CASCADE workflow (Loose Ends → Task Selection → Execution)
Two-queue system (manual + generated priorities)
Safety guardrails (GREEN/YELLOW/RED operation classification)
Session documentation and state management
Multi-backend: Supports both gptme and Claude Code backends

Forking (manual alternative)

If you prefer to fork manually instead of using gptme-agent create:

git clone https://github.com/gptme/gptme-agent-template
cd gptme-agent-template
git submodule update --init --recursive

./scripts/fork.sh <path> [<agent-name>]

Then follow the instructions in the output.

Domain Agent Apps

Use knowledge/portable-agent-apps.md when packaging a domain-specific agent app from this template. The short version: keep one shared workflow contract, expose it through thin runtime adapters, and preserve user-owned state across system updates.

Workspace Structure

gptme-agent keeps track of tasks in TASKS.md
gptme-agent keeps a journal in ./journal/
gptme-agent keeps a knowledge base in ./knowledge/

- gptme-agent maintains profiles of people in [`./people/`](./people/) - gptme-agent manages work priorities in [`./state/`](./state/) using the two-queue system (manual + generated) - gptme-agent uses scripts in [`./scripts/`](./scripts/) for context generation, task management, and automation

gptme-agent can add files to gptme.toml to always include them in their context

Key Directories

**[`state/`](./state/)**: Work queue management

queue-manual.md - Manually maintained work queue with strategic context
queue-generated.md - Auto-generated queue from tasks and GitHub
See state/README.md for detailed documentation

**[`scripts/`](./scripts/)**: Automation and utilities

context.sh - Main context generation orchestrator
gptodo - Task management CLI (install from gptme-contrib)

- `runs/autonomous/` - Autonomous operation infrastructure - See [`scripts/README.md`](./scripts/README.md) for complete documentation

lessons/: Behavioral patterns and constraints

Prevents known failure modes through structured guidance
See lessons/README.md for lesson system documentation