agent

Documentation

Overview

Package agent models a durable companion agent: a persistent home directory holding the agent's persona (SOUL.md), its MCP server declaration (mcp.json), and its Claude settings (settings.json). The agent is materialized into a disposable session worktree by Agent.Materialize, which copies those files into the worktree as the files Claude Code auto-reads when its cwd is the worktree (.claude/CLAUDE.md, .mcp.json, .claude/settings.json). The model is domain-neutral: callers (e.g. Neublox's Roblox profile) supply the persona and MCP server; the package only stores and materializes them.

Index

• func UserBudgetFromEnv(get func(string) string) (int, bool)
• type Agent
  • func (a Agent) Materialize(worktree string) error
• type CreateSpec
• type Store
  • func NewStore(root string) *Store
  • func (s *Store) Create(spec CreateSpec) (Agent, error)
  • func (s *Store) Get(name string) (Agent, bool)
  • func (s *Store) List() ([]Agent, error)
  • func (s *Store) Root() string
  • func (s *Store) SetSoul(name, soul string) error
  • func (s *Store) SetUser(name, text string) error
  • func (s *Store) SetUserBudget(runes int)

Functions

func UserBudgetFromEnv

func UserBudgetFromEnv(get func(string) string) (int, bool)

UserBudgetFromEnv parses AGENT_USER_BUDGET via get (os.Getenv in production). It returns (0, false) when the variable is unset or not an integer, so the caller keeps the default budget; a valid value (including 0, which disables the check) returns (n, true).

Types

type Agent

type Agent struct {
	Name    string
	Home    string   // absolute path to the agent's home directory
	Tags    []string // capability tokens from <home>/TAGS (nil when absent), for host routing
	Backend string   // backend vendor from <home>/backend, empty when absent
	Cmd     string   // default invocation from <home>/cmd, empty when absent
}

Agent is a durable companion: a name, backend vendor, and the home directory that stores its persona and provisioning files.

func (Agent) Materialize

func (a Agent) Materialize(worktree string) error

Materialize provisions the agent into a session worktree by writing the files Claude Code and Codex read from its working directory:

<worktree>/.mcp.json             (from <home>/mcp.json)
<worktree>/.claude/settings.json (from <home>/settings.json)
<worktree>/.claude/CLAUDE.md     (from <home>/SOUL.md — the layered persona)
<worktree>/AGENTS.md             (from <home>/SOUL.md)
<worktree>/.claude/USER.md       (from <home>/USER.md, when present)
<worktree>/.codex/config.toml    (converted from <home>/mcp.json)

When <home>/USER.md exists, it is also referenced from CLAUDE.md via a Claude Code @import and inlined into AGENTS.md (Codex has no import mechanism). Without a USER.md, CLAUDE.md and AGENTS.md are byte-identical to SOUL.md.

Any worktreeToken in a source file is replaced with the worktree path.

type CreateSpec

type CreateSpec struct {
	Name    string
	Soul    string
	User    string
	MCP     string
	Backend string
	Cmd     string
	Tags    []string
}

CreateSpec declares a new agent. Soul is the persona text (SOUL.md); MCP is an optional stdio MCP server command line ("neublox serve --project {{WORKTREE}}") whose first token names the server and is its command.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store owns the directory holding every agent home: <root>/<name>/.

func NewStore

func NewStore(root string) *Store

NewStore returns a Store rooted at root (created lazily on first Create).

func (*Store) Create

func (s *Store) Create(spec CreateSpec) (Agent, error)

Create writes a new agent home and seeds its source files. It errors if the name is unsafe or the agent already exists.

func (*Store) Get

func (s *Store) Get(name string) (Agent, bool)

Get returns the agent named name, or false if no such home directory exists.

func (*Store) List

func (s *Store) List() ([]Agent, error)

List returns every agent home under the store root, sorted by name. A missing root yields an empty list (no agents created yet).

func (*Store) Root

func (s *Store) Root() string

Root returns the directory under which agent homes live.

func (*Store) SetSoul

func (s *Store) SetSoul(name, soul string) error

SetSoul overwrites <home>/SOUL.md for an existing agent. It never creates a home — an absent agent is an error (callers seed via Create). Homes are the source of truth; an edited soul applies to the next session materialized.

func (*Store) SetUser

func (s *Store) SetUser(name, text string) error

SetUser overwrites <home>/USER.md for an existing agent, rejecting content over the store's user budget (contracts.EnforceBudget) before touching disk. It never creates a home — an absent agent is an error.

func (*Store) SetUserBudget

func (s *Store) SetUserBudget(runes int)

SetUserBudget overrides the per-agent USER.md rune budget. A value <= 0 disables the check (see contracts.EnforceBudget).