Introduction

Agents are Lua-defined autonomous workers that handle complex, multi-step tasks. They run independently with their own tool sets, iteration limits, system prompts, and hook-based nudge systems.

Agent Folder Structure

Each agent lives in $WORKSPACE/agents/<name>/ with two files:

agents/
└── my-agent/
    ├── agent.lua    # Configuration and hooks (required)
    └── prompt.md    # System prompt template (required)

Simple Example

agents/chat-reflection/agent.lua

local template = require("ghost.template")

return {
    name = "chat-reflection",
    description = "Reflection on operator chat sessions",
    max_iterations = 30,
    tools = {
        "shell", "file_read", "file_write",
        "file_edit", "knowledge_search", "note_write",
    },
    skills = { "knowledge-navigator", "note-writer" },
    build = function(ctx, args)
        return {
            system_prompt = template.render(read_file("prompt.md"), {
                date = os.date("%Y-%m-%d"),
            }),
            messages = {
                { role = "user",
                  content = args.prompt or "Begin reflection." },
            },
        }
    end,
}

Default Agents

GHOST ships three built-in agents, installed into $WORKSPACE/agents/ on workspace bootstrap:

Agent	Purpose
deep-research	Iterative web research with full page reading and source evaluation
chat-reflection	Knowledge extraction from idle chat sessions (scheduled via crontab.lua)
deep-research-reflection	Knowledge extraction from completed research (spawned by report_findings handler in deep-research)

How Agents Work

1. Agent is triggered (manual dispatch, cron schedule, idle timeout, or spawned by another agent)
2. The build(ctx, args) hook produces a system prompt and initial messages
3. Agent runs autonomously with its restricted tool set, guided by nudge hooks
4. When the agent finishes (text-only response or terminal custom tool), findings are captured
5. For dispatched agents, findings are injected back into the parent chat session
6. Terminal custom tool handlers can spawn child agents with structured data via ctx:spawn_agent()

Running Agents

ghost agent list               # List available agents
ghost agent validate <name>    # Validate an agent's Lua config
ghost agent run <name> [prompt] # Run an agent manually
ghost agent logs [name]        # View agent run logs

During conversation, GHOST can also spawn and manage agents with the agent tool.