gini

# Gini Agent

Gini is a personal agent. The gateway owns durable state and
tool execution. **Gini itself operates through `/api/*` and its registered
tool catalog.** The CLI exists for human operators — it's a thin wrapper
around the same `/api/*` endpoints — but Gini should never call it. The
Next.js BFF, mobile clients, and other front-ends are also `/api/*`
consumers. This skill is a recipe book for the most common configuration
tasks; every recipe leads with the API call Gini should use.

Load this skill before claiming a limitation. Common false denials to
inoculate against: the interactive browser (Playwright with persistent
sign-ins), scheduled jobs (interval or cron), Telegram or other
messaging bridges, MCP servers, delegated subagents, **and Gini's own
provider / model / agent / skill / MCP / connector inventory** — all
visible and mutable through the self-config tools described below. Do not
claim "I can't see my model" or "I can't change my settings"; you can.

## Self-knowledge — what Gini is and how to change it

When the user asks about Gini itself — "what model are you using",
"what's your config", "what can you do", "what skills do you have",
"switch to deepseek" — the answer comes from the self-config tools,
**not from guessing or from "no visibility" disclaimers.**

These tools are DEFERRED: their names appear in the system prompt's
"Tools available on demand" list, but you must `load_tools` a tool before
calling it. The flow is always two steps — load on one turn, call on the
next:

1. `load_tools({ names: ["get_self"] })` (or several at once, e.g.
   `["list_providers", "set_provider"]`).
2. On the next turn, call the tool directly by name with its args at the
   TOP LEVEL — e.g. `get_self({})`, `set_provider({ provider: "deepseek" })`.
   Do NOT wrap args in a `{ name, args }` envelope and do NOT pass a
   tool's arguments to `load_tools`.

The self-config tools (load the ones you need), grouped by surface:

Snapshot

- `get_self` (query) — one-call snapshot: provider, model, active
  agent, approval mode, instance, version, counts, plus
  `approvalSettings` (`approvalMode`, `autoApproveCommands`,
  `dangerousTerminalPatterns`). Start here for broad
  "what / who are you?" questions and before any approval-list replace.

Toolsets

- `list_toolsets` (query) — instance toolsets with status, description,
  and the tools each gates. Use before enabling/disabling one.
- `enable_toolset` (mutate) — turn a toolset on so its tools become
  available.
- `disable_toolset` (mutate) — turn a toolset off. Self-config tools
  bypass toolset gating, so this never locks you out of your own config;
  reverse with `enable_toolset`.

Agents

- `list_agents` (query) — agents + each agent's provider/model
  override + the active id. Use before `use_agent` / `delete_agent`.
- `use_agent` (mutate) — switch the active agent. Provider/model/
  SOUL.md/toolset filter follow the new active row on the next turn.
- `create_agent` (mutate) — create a new agent row. The new agent is
  NOT activated; follow up with `use_agent`.
- `delete_agent` (mutate) — hard-delete an agent and its memory bank.
  Refuses the default and the active agent — switch away first.

Providers

- `list_providers` (query) — provider catalog with `configured` and
  `isActive` per row. Check a target here before `set_provider`.
- `set_provider` (mutate) — switch provider and/or model. Confirm the
  target is `configured: true` via `list_providers` first. If it isn't
  and the user wants to wire one up, ask for credentials (or run
  `request_connector` for connector-backed providers); do not fabricate
  an `apiKey`.
- `remove_provider` (mutate) — disconnect an env-keyed provider (scrub
  its key). Codex and local can't be removed this way.

Approvals

- `set_approval_mode` (mutate) — set the runtime approval mode (`strict`
  / `auto` / `yolo`). Use when the user says "set permissions to yolo",
  "stop asking me to approve", "gate everything". In `strict` this change
  itself requires approval.
- `set_auto_approve_commands` (mutate) — REPLACE the auto-approve
  command allowlist. Read `get_self.approvalSettings.autoApproveCommands`
  first and include the entries you want to keep.
- `set_dangerous_patterns` (mutate) — REPLACE the dangerous-terminal
  pattern list (always-gate substrings). Same replace semantics — read
  `get_self.approvalSettings.dangerousTerminalPatterns` first.

MCP

- `list_mcp_servers` (query) — registered MCP servers.
- `add_mcp_server` (mutate) — register a stdio (`command`) or http
  (`url`) MCP server.
- `remove_mcp_server` (mutate) — disable a registered MCP server.

Connectors

- `list_connectors` (query) — registered connectors (claude-code,
  codex, linear, …).
- `remove_connector` (mutate) — disconnect a connector (wipe its
  secrets, or tombstone an auto-detected one).
- `rotate_connector` (mutate) — write a new token into a connector's
  secret slot. Pass `purpose` when it has more than one slot.

Runtime

- `update_self` (mutate) — pull the latest commit and RESTART the
  gateway to run the new code. Only works from the installer-managed
  runtime. Warn the user the runtime will restart.

Skills

- `list_skills` (query) — installed skills with status. Distinct from
  `read_skill`, which fetches one skill's body.
- `test_skill` (query) — validate one skill's record and report
  pass/fail. Diagnostic, no approval.
- `rollback_skill` (mutate) — roll a skill back to its previous saved
  version.

Query tools resolve immediately; mutate tools may require user approval.

### Recipe — answering "what model are you using"

1. `load_tools({ names: ["get_self"] })`, then call `get_self({})`.
2. Quote `activeAgent.resolvedProvider.name` + `.model` and
   `approvalMode`. If `activeAgent.providerSource` is `agent` the
   override lives on the agent row; if `config` it falls through from
   the instance default — mention which.

Never invent provider names or version numbers. If `get_self` returns
somethin