Persona-Grata

Persona-Grata is a scaffolding utility that binds AI personas to harnesses to produce an embodied, functional agent. It helps users connect professional LLM orchestration harnesses (e.g., Claude Code, the Codex CLI, and Goose) with customized endpoints.

Install

Install via pipx, uv, or your other favorite package management tool:

pipx install persona-grata

Run

Run it directly:

persona-grata <persona> [harness]*

Examples

To install a persona for the official kimi servers and use it with Claude Code:

persona-grata kimi claude

If you have custom endpoints or other settings, create and run with an agent file:

persona-grata custom_agents.yaml

Read more about configurations in the Custom Agents Guide.

Overview: Agents, Personas, & Harnesses

We combine a persona (representing the mind and experience) with a harness (the mechanism used to impact the world) to yield an agent.

...but what does that actually mean?

An agent is an entity that can act on the world around it - it has a model of its universe, an inference-based (data-derived) decision-making process, a set of actions, and some knowledge of the results of its actions (see also The Craik Model of Intelligence.) An agent requires not just the ability to think, but also the ability to act.

A persona is that thinking part of an agent - i.e., its 'mind' (endpoint, model, & parameters) and 'experiences' (system prompt, context, etc.)

To interact with the world, we can use a harness (sometimes called an orchestrator) to provide toolsets and communication mechanisms; these include Claude Code, Codex CLI, Goose, & many others.

By combining a persona with a harness, we get the fully embodied agent.

Usage

The utility reads agent definitions from a provided YAML file (which describes how personas connect to harnesses) and configures your local environment. The sample agents-example.yaml file can serve as a starting point; the bundled harness profiles are 'ready' to go and do not require modification.

Known Endpoints & Harnesses

Persona-Grata comes with "out of the box" support for the following endpoints and harnesses; for each endpoint, a default persona is derived:

Endpoint Personas: kimi, local_8000, local_8080, local_lemonade, local_llamacpp, local_lmstudio, local_ollama, minimax, navigator

Coding Harnesses: claude, codex, goose

Setup an Agent

To setup an agent from a persona and harness, run persona-grata <persona> [harness]*:

persona-grata kimi

Sets up kimi for all known harnesses

persona-grata minimax claude codex

Sets up minimax for use with Claude Code and Codex CLI

If you need a more customized solution, an agent definition file provides additional flexibility:

agents.yaml

personas:
  orion:
    persona_desc: "Orion Toolkit"
    mind:
      endpoint: "https://api.cybertron.space"
      model: "alpha-3-on"

Then, run:

persona-grata agents.yaml orion claude

Setup the custom persona (Orion Toolkit) with Claude Code.

Or, to install all agents and harnesses, run without persona and/or harness names:

persona-grata agents.yaml

Setup every persona in the file with all known harnesses.

pg is a shorter alias for the same command: pg kimi claude.

Designations & Names

An agent's designation is <persona>+<harness>. It names one agent, so it settles the harness on its own:

pg kimi+claude

The same as pg kimi claude.

A name is yours to choose, and is how the agent is invoked. Pass --name to set one:

pg --name scout local_ollama+codex

Sets up the agent and installs it as scout rather than local_ollama-codex.

A name replaces that command rather than adding a second one, so an agent always has exactly one way to run it; naming it again renames it. Use the name wherever a designation goes — pg -r scout removes it, and releases the name. An agent you never name keeps its designation as its name.

Create a Configuration via CLI

For one-off variants or local model servers, persona configurations can be defined by arguments:

pg --endpoint http://localhost:8675 --model llama3 --no-token ollama claude

Sets up a local Ollama model as the persona "ollama", for Claude Code.

The CLI can also be used to update an existing persona:

pg --update --model kimi-k2-0905-preview kimi codex

Sets kimi up with Codex CLI, using a different model just this once.

By default, a definition is ephemeral, but the configuration can be exported if desired:

pg --endpoint http://who.dr:99 --model llama3 --no-token --export "clauma.yaml" ollama claude

Exports the configuration to clauma.yaml.

Export, update, and new persona creation are mutually exclusive:

The API key/token can be read, verified, then stored directly, replacing any existing key/token:

pg --token ~/keys/moonshot.key kimi claude

Sets kimi up with Claude Code, taking the key from ~/keys/moonshot.key.

The same settings can also be asked for rather than typed:

pg -i

Asks for a name, description, endpoint, model, key, and harnesses, then offers to save the result.

Interactive mode supplies whatever flags did not, combining one of the actions above; e.g., pg -i --update kimi only asks for missing elements. It cannot be paired with --remove.

Remove an Agent

Pass --remove (or -r) to remove the harness-persona wrapper & harness config directory:

pg --remove kimi codex

Removes the Codex CLI agent for kimi, leaving Claude Code and the stored token alone.

pg --remove kimi

Removes every kimi harness, then asks whether to delete the stored API token, if there is one.

Interaction

The script automatically adds a shell wrapper to your .bashrc, .zshrc, or .profile, depending on your shell. After running setup and sourcing your config (source ~/.bashrc) or opening a new terminal, you can launch the agent:

<persona>-<harness> [arguments]

A $SHELL persona-grata doesn't recognise is reported, not assumed; the wrapper is written in plain POSIX shell syntax, so any POSIX shell will run it.

Parameters Summary

*If the --no-token flag is not included, connections to keyless-only servers will fail.

^--token and --no-token are mutually exclusive.

Agent Configuration & Templates

Definitions are managed in an agent YAML file. It describes one or more personas and/or harnesses. Persona-Grata supports a dynamic variable resolution system via {{variable}} syntax.

• Context Lookup: Resolves variables defined in current context (e.g., {{pid}}, {{path}}).
• Hierarchical References: Absolute references to any value in agents.yaml via dot-notation (e.g., {{personas.orion.mind.model}}).
• Reserved Identifiers: {{__PARENT__}} resolves to the immediate parent node in the configuration tree and {{__KEY__}} to a node's own key, so {{__PARENT__.__KEY__}} in a persona definition yields that persona's ID.
• Templated Keys: dict keys may hold templates too, so a config section can be named from a value (e.g., "{{hid}}": under model_providers yields [model_providers.codex]).
• Serializers: a reference may end in __AS_JSON__(), __AS_TOML__(), or __AS_YAML__() to render a whole subtree as a harness config file (e.g., content: "{{config_store.__AS_JSON__()}}").
• Subscripts: any segment may be indexed by another reference, resolved where the template is written rather than where it points (e.g., {{providers[chosen].url}} is "the entry of providers named by my chosen"). Subscripts chain, and index lists by position — [1], [-1] included.
• Functions: a reference may instead be a call, {{__NAME__(arg, ...)}}, whose arguments are themselves references. __MATCH_FIRST__(key_set, items) yields the first member of key_set found among items' keys, reading the list as a preference order.

Environment variables ($FOO, ${FOO}) are also substituted, in a single pass, before the file is parsed. Write $$ for a literal dollar sign — $$HOME yields the text $HOME.

For more about templates & configuration, see the Config Reference Manual.

Security

To prevent secret leakage:

• API tokens are stored in files with 0600 permissions.
• The utility handles tokens by path, avoiding printing secrets to logs or transcripts.
• A .secret_path file is created in the persona's home directory containing the path to the token for discovery by other tools.

License & Contributing

Persona-Grata is released under the GNU General Public License v3.0 or later; see LICENSE.md.

Contributions generated in whole or in part with AI tools are welcome, subject to the project's AI policy.