Creating Psychonauts

Simple Psychonaut

Most psychonauts are just configuration — name, prompt, tools, model:

.annihilation/agents/my_agent.ex

defmodule MyAgent do
  use Annihilation.Agent.Template

  def name, do: "my_agent"
  def description, do: "A custom psychonaut for my project"
  def model, do: "claude-sonnet-4-20250514"

  def system_prompt do
    """
    You are a specialized psychonaut for this project.
    Focus on writing clean, well-tested Elixir code.
    """
  end

  def tools do
    [Annihilation.Tools.Shell, Annihilation.Tools.FileRead, Annihilation.Tools.FileWrite]
  end
end

Place it in $PROJECT_ROOT/.annihilation/agents/ for project-local, or ~/.annihilation/agents/ for global.

Advanced Psychonaut (Lifecycle Hooks)

Override optional callbacks for custom behavior:

defmodule SmartReviewer do
  use Annihilation.Agent.Template

  def name, do: "smart_reviewer"
  def description, do: "Reviews code with custom post-processing"
  def model, do: "claude-sonnet-4-20250514"
  def system_prompt, do: "You review code for bugs, security, and style."
  def tools, do: [Annihilation.Tools.FileRead, Annihilation.Tools.Shell]

  # Custom: increase max turns for thorough reviews
  def constraints, do: [max_turns: 100, max_tokens: 8192]

  # Custom: parse structured findings from LLM output
  def on_streaming_done(state, response) do
    # Post-process the response
    response
  end

  # Custom: retry with a different provider on error
  def on_error(state, {:rate_limited, _}, _ctx) do
    {:retry, %{state | model: "gpt-4o"}}
  end
  def on_error(_state, _error, _ctx), do: :continue
end

Auto-Generated Psychonauts

Ask the builder psychonaut to create one:

/dispatch builder "Create a psychonaut that monitors test coverage and flags regressions"

The builder generates the module → it goes to Grounding → you review and ground → it’s hot-loaded.