Agents#
Commands for creating, running, and managing persistent autonomous agents. See Agents.
gptme-agent#
Manage gptme autonomous agents.
This command helps you set up, install, and manage autonomous gptme agents that run on a schedule using your system’s service manager (systemd on Linux, launchd on macOS).
Usage
gptme-agent [OPTIONS] COMMAND [ARGS]...
Options
- -v, --verbose#
Enable verbose output.
create#
Create a new persistent agent workspace.
PATH is the directory where the agent workspace will be created. A persistent agent workspace contains identity files (SOUL.md, GOALS.md, …), knowledge, lessons, and automation scaffolding — not just a service runner.
Usage
gptme-agent create [OPTIONS] PATH
Options
- -n, --name <name>#
Agent name (defaults to directory name)
- -t, --template, -T, --no-template#
Use template repository (default: yes)
- --template-repo <template_repo>#
Template repository URL (default: gptme/gptme-agent-template)
- --template-branch <template_branch>#
Template branch (default: master)
- --init-conversation#
Initialize first conversation for the agent
Arguments
- PATH#
Required argument
doctor#
Check workspace health and readiness.
Validates that an agent workspace is properly configured for autonomous operation. Checks core files, configuration, directory structure, tools, git setup, and more.
PATH is the workspace directory to check. Defaults to the current directory.
Usage
gptme-agent doctor [OPTIONS] [PATH]
Options
- --fix#
Attempt to fix simple issues automatically
Arguments
- PATH#
Optional argument
install#
Install agent services.
Creates and enables systemd service/timer (Linux) or launchd plist (macOS) for the agent to run on the specified schedule.
Usage
gptme-agent install [OPTIONS]
Options
- -n, --name <name>#
Agent name (defaults to current directory name)
- -w, --workspace <workspace>#
Workspace path
- -s, --schedule <schedule>#
Schedule (systemd calendar format). Default: every 30 minutes
list#
List all installed agents.
Usage
gptme-agent list [OPTIONS]
logs#
View agent logs.
Shows recent log output from the agent’s autonomous runs.
If NAME is not provided, shows logs for the agent in the current directory.
Usage
gptme-agent logs [OPTIONS] [NAME]
Options
- -n, --lines <lines>#
Number of lines to show
- -f, --follow#
Follow log output
Arguments
- NAME#
Optional argument
restart#
Restart agent(s).
If NAME is not provided, restarts the agent in the current directory.
Usage
gptme-agent restart [OPTIONS] [NAME]
Arguments
- NAME#
Optional argument
run#
Trigger an immediate agent run.
Starts a one-time execution of the agent’s autonomous run script. This is useful for testing or manually triggering work.
If NAME is not provided, runs the agent in the current directory.
Usage
gptme-agent run [OPTIONS] [NAME]
Arguments
- NAME#
Optional argument
scan#
Scan for live agent processes (gptme, claude-code, codex, aider, …).
Inspects currently running processes on this host. This is about live sessions and processes — NOT about persistent agents, brain-workspaces, or agent identities. A result here means a process is actively running right now; it says nothing about that agent’s workspace or identity files.
To create or manage a persistent agent workspace, see: gptme-agent create
Usage
gptme-agent scan [OPTIONS]
Options
- -w, --workspace <workspace>#
Only show agents whose CWD is under this path. By default all agents on the host are shown.
- --all#
Include stale/stuck agents (excluded by default).
- --json#
Output as JSON.
start#
Start agent(s).
Enables the timer/scheduler for the agent to run on schedule. If NAME is not provided, starts the agent in the current directory.
Usage
gptme-agent start [OPTIONS] [NAME]
Arguments
- NAME#
Optional argument
status#
Show status of agent(s).
If NAME is provided, shows status for that specific agent. Otherwise, shows status for all installed agents.
Use –all to also show detected workspaces that haven’t been installed yet.
Usage
gptme-agent status [OPTIONS] [NAME]
Options
- -a, --all#
Show all detected workspaces, including not installed
Arguments
- NAME#
Optional argument
stop#
Stop agent(s).
Disables the timer/scheduler to pause scheduled runs. If NAME is not provided, stops the agent in the current directory.
Usage
gptme-agent stop [OPTIONS] [NAME]
Arguments
- NAME#
Optional argument
uninstall#
Uninstall an agent’s services.
Removes the systemd/launchd service files for the specified agent. This does NOT delete the workspace directory.
Usage
gptme-agent uninstall [OPTIONS] NAME
Options
- -y, --yes#
Skip confirmation
Arguments
- NAME#
Required argument
gptme-service#
Manage persistent headless gptme agent services.
Usage
gptme-service [OPTIONS] COMMAND [ARGS]...
init#
Scaffold a minimal persistent service for a headless gptme agent (systemd on Linux, launchd on macOS). For the full workspace template, see gptme/gptme-agent-template.
Usage
gptme-service init [OPTIONS]
Options
- -n, --name <name>#
Required Agent name (used for the service unit and agent identity).
- -m, --model <model>#
Default model for the agent.
- Default:
'gpt-4o-mini'
- -d, --work-dir <work_dir>#
Agent work directory (created if missing).
- Default:
'~/gptme-agent'
- -o, --output-dir <output_dir>#
Directory to write service files. Defaults to ~/.config/systemd/user (Linux) or ~/Library/LaunchAgents (macOS).
- --timer-schedule <timer_schedule>#
Timer schedule. ‘on-demand’ writes no timer (manual start only).
- Default:
'daily'- Options:
hourly | daily | weekly | on-demand
- --platform <platform_choice>#
Target platform. ‘auto’ detects the current system.
- Default:
'auto'- Options:
linux | macos | auto
- --force#
Overwrite existing generated files.
- --enable-health-check#
Generate a local JSON health probe (Linux/systemd only).