Agency

Appearance

The Agency assistant agent ​

Work in progress

agency agent

Launches the Agency language assistant agent — an LLM agent that knows about Agency's syntax, standard library, and idioms. You can ask it to write Agency code, explain language features, debug an error, or walk through a piece of code with you.

This is a convenient way to get help with Agency without leaving your terminal.

Approval flags ​

The agent asks before doing anything its policy does not already decide. Three flags shape that for a single session:

agency agent --policy with-writes
agency agent --approve FileRead --reject Shell

--policy picks the base policy (a built-in name or a policy-file path); --approve and --reject overlay effects or effect-set names on top of it. None of these change your saved policy.json. See the policy flags for the details and agency effects for the names they accept.

Budget flags ​

  • agency agent --max-cost <dollars> — abort if the agent's LLM spend exceeds this many dollars. 0 means no paid spend (local models only); negative means no limit.
  • agency agent --max-time <duration> — abort if the agent's working time exceeds this duration, e.g. 30m. The value needs a unit (30s, 5m, 1h, 2d, 1w). Time spent waiting for your input does not count. Zero or negative means no limit.

A tripped budget exits with code 3, distinct from 1 (crash) and 2 (usage error), so scripts can tell an overrun apart from a failure.

The agent home directory ​

The agent keeps its state — settings.json, policy.json, and conversation history — in ~/.agency-agent. You can point it at a different directory:

agency agent --agent-home /path/to/dir

or with the AGENCY_AGENT_HOME environment variable:

AGENCY_AGENT_HOME=/path/to/dir agency agent

The flag wins when both are set. An empty value is treated as unset. This is useful for keeping separate agent profiles (say, different policies or model settings per project), and for sandboxing: the test harness uses it to give every test its own throwaway agent home so runs never touch your real ~/.agency-agent.