Aegis documentation

#ai — providers, models, agents and chats

The AI module gives this host an agent that knows it: providers and their API keys, a model catalogue, agents with instructions and attachments, tools and skills, chats in the terminal, one-shot prompts, and a background queue that a keeper service drains.

Everything the commands write lives in database/storage/ai/ai.db. Everything that comes from a file — the shipped agents and skills — is owned by that file and rewritten by aegis ai setup; the command line owns only the rows it created itself.

bash
aegis ai                    # the command list and examplesaegis ai help               # the sameaegis ai providers list

Every listing command also accepts aegis --json ai …, which prints one JSON object instead of the table. The flag goes before the group, on the root command.

#The catalogue at a glance

CommandWhat it manages
aegis ai providersendpoints, their keys and which one is the default
aegis ai modelscontext windows, output limits, capabilities and prices
aegis ai setupthe whole catalogue, in dependency order, in one step
aegis ai agentsinstructions, loop limits and what an agent attaches
aegis ai toolsthe tool catalogue, grouped in packs
aegis ai skillsprompt blocks agents carry
aegis ai chata conversation in the terminal
aegis ai promptone turn, printed, or queued in the background
aegis ai jobsthe background queue and its history
aegis ai answerthe questions a background turn is waiting on
aegis ai daemonthe background worker, in the foreground

#Where the data lives

text
config/ai.toml                       credentials, defaults, limitsdatabase/storage/ai/ai.db            the catalogue and every transcriptstorage/ai/agents/<slug>/agent.md    system agents (file-owned)storage/ai/skills/<category>/<slug>/skill.mdrun/ai.pid, run/ai.lock, run/ai.heartbeat   the background daemonlogs/ai.log                          what the daemon printed

Providers come from config/ai.toml ([providers.<slug>]) and from the driver declarations under app/modules/ai/providers/; a sync writes both. An agent or skill whose source_path is set is read-only from the command line: the file owns it, and a sync reconciles its row. One created with add has no file and is edited and removed here.

#Providers

A provider is one endpoint, one key and one driver. The driver is code: it decides how a request is shaped, so a provider named in the config whose driver this build does not ship is reported instead of guessed.

#aegis ai providers list

Print every provider with the source of the key it uses, its default flag, the number of models it has and its endpoint. The key column reads db when set-key wrote the secret, config when it comes from config/ai.toml, and missing when there is none.

bash
aegis ai providers list
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis ai providers listaegis --json ai providers list
text
slug      driver    default  status  key          models  url────────  ────────  ───────  ──────  ───────────  ──────  ────────────────────────────deepseek  deepseek  yes      active  db …a1b2     2       https://api.deepseek.com/v1xai       xai                active  config …9f3c  8       https://api.x.ai/v1

When the table is empty the command says so and returns 0:

text
ℹ no provider yet; run `aegis ai providers sync`

#aegis ai providers show

Print one provider as a key/value block, followed by its models in the same shape aegis ai models list uses. The key is shown by source and masked to its last four characters.

bash
aegis ai providers show <slug>
ArgumentDefaultMeaning
slugrequiredprovider slug, for example deepseek
bash
aegis ai providers show deepseekaegis ai providers show xai
text
slug      deepseekname      DeepSeekdriver    deepseekapi_url   https://api.deepseek.com/v1status    activedefault   yeskey       db …a1b2provider  model             context  output  tools  reasoning────────  ────────────────  ───────  ──────  ─────  ──────────────────deepseek  deepseek-flash    1M       384k    yes    none, low, high, maxdeepseek  deepseek-v4-pro   1M       384k    yes    none, low, high, max

An unknown slug prints ✖ unknown provider: openai and exits 1.

#aegis ai providers sync

Write the providers declared in config/ai.toml and every model declared by the drivers into ai.db. This is the same handler as aegis ai models sync: both write the whole catalogue. It never copies a key out of the config, keeps the key already stored on a row, and never deletes a row, so it is safe after every deploy.

bash
aegis ai providers sync
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis ai providers syncaegis ai providers sync && aegis ai providers list
text
✔ 2 providers, 10 models, 60 prices

A provider in the config that this build has no driver for is reported on stderr, and the rest of the sync still runs:

text
⚠ xai-experimental: no driver for that provider in this build✔ 2 providers, 10 models, 60 prices

#aegis ai providers set-key

Store an API key on a provider row. The database wins over the config, so this is how a key is overridden without editing config/ai.toml. Without --key the value is read from the terminal with echo off, which keeps it out of the shell history.

bash
aegis ai providers set-key <slug> --key <secret>
OptionDefaultMeaning
--key""the secret; asked for when omitted
bash
aegis ai providers set-key deepseekaegis ai providers set-key xai --key "xai-…"
text
api key for deepseek:✔ deepseek: key stored (…a1b2)

An empty answer, or a key for an unknown provider, exits 1 with a message. The full key is never printed.

#Models

A model row carries the facts a provider API does not report: context window, output limit, feature flags, aliases, reasoning efforts and effective-dated prices. A sync writes every model the drivers declare; it never deletes one.

#aegis ai models list

Print the models, one per row, with the provider they belong to. Context and output are shortened (1M, 384k); a model that declares neither shows blank cells.

bash
aegis ai models list --provider <slug> --all
OptionDefaultMeaning
--provider""only the models of this provider slug
--alloffinclude the models marked inactive
bash
aegis ai models listaegis ai models list --provider deepseekaegis ai models list --all
text
provider  model             context  output  tools  reasoning────────  ────────────────  ───────  ──────  ─────  ──────────────────deepseek  deepseek-flash    1M       384k    yes    none, low, high, maxdeepseek  deepseek-v4-pro   1M       384k    yes    none, low, high, maxxai       grok-4.7                          yes    low, medium, high, xhigh

reasoning lists the effort levels the model accepts, or no when it has none. An empty catalogue prints:

text
ℹ no model yet; run `aegis ai providers sync`

#aegis ai models sync

Write the declared models, their feature flags and their prices into ai.db. Prices are effective-dated: an unchanged number is left alone, a changed one closes the old row and opens a new one, so a past turn can be repriced with the rate that was valid when it ran.

bash
aegis ai models sync
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis ai models syncaegis ai models sync && aegis ai models list
text
✔ 2 providers, 10 models, 60 prices

#Setup

#aegis ai setup

Write the whole catalogue in the order the dependencies allow: providers, then models and prices, then tools, then skills, then agents. Every step is an upsert; nothing edited by hand is lost and a row whose file disappeared is archived rather than deleted. It prints one animated line while it works, then a summary. It does not start the daemon.

bash
aegis ai setup --check
OptionDefaultMeaning
--checkoffask every provider that has a key for its model list
bash
aegis ai setupaegis ai setup --check
text
✔ Aegis AI systems ready in 1.6sproviders  2 (keys: deepseek: db, xai: config)models     10tools      41 in 12 packsskills     10agents     2ℹ next: aegis ai prompt "salut" --agent aegisℹ       aegis ai daemon start

With --check, a second table reports whether each key works. One request per provider, no retries, and the key is never printed:

text
provider  result  detail────────  ──────  ────────deepseek  ok      2 modelsxai       failed  HTTP 401

A provider with no key at all reports no key. The command keeps its exit code 0 even when a check fails; the table is the answer.

#Agents

An agent is identity, instructions, loop limits, a model and the tools, skills and sub-agents it attaches. The three kinds are master, sub-agent and utility. The shipped aegis (master) and scout (read-only sub-agent) live as files under storage/ai/agents/; the command line can attach and detach things on them but cannot edit or delete their rows.

#aegis ai agents list

Print every agent with its kind, model, step limit, parallelism and attachment counts. steps is the agent's own max_steps; parallel is yes only when the agent may run sub-agents and tools concurrently.

bash
aegis ai agents list --kind <kind>
OptionDefaultMeaning
--kind"" (all)master, sub-agent or utility
bash
aegis ai agents listaegis ai agents list --kind sub-agent
text
slug   kind       model           steps  parallel  tools  skills  status─────  ─────────  ──────────────  ─────  ────────  ─────  ──────  ──────aegis  master     deepseek-flash  25     yes       41     10      activescout  sub-agent  deepseek-flash  12               24     10      active

An empty catalogue prints ℹ no agent yet; run aegis ai setup``.

#aegis ai agents show

Print one agent's fields, then its instructions, then three tables: attached tools, skills and sub-agents. An empty attachment block prints (none).

bash
aegis ai agents show <slug>
ArgumentDefaultMeaning
slugrequiredagent slug, for example aegis
bash
aegis ai agents show aegisaegis ai agents show scout
text
slug       aegisname       Aegiskind       mastermodel      deepseek-flashstatus     activemax_steps  25parallel   yessource     /aegis/storage/ai/agents/aegis/agent.md# Who you areYou are Aegis, the system agent of this host. …tools:  tool             pack     status  ───────────────  ───────  ──────  aegis.command    aegis    active  files.read       files    active  shell.run        shell    activeskills:  skill              name                category  ─────────────────  ──────────────────  ────────  platform-overview  Platform overview   aegis  conventions        Project conventions aegissub-agents:  agent  name   kind  ─────  ─────  ─────────  scout  Scout  sub-agent

The instructions are printed in full; the excerpt above is shortened here for space. The three attachment tables are also abridged here: the command prints every row. source reads command line for an agent created with add.

#aegis ai agents add

Create an agent that has no file. The command line owns it from then on.

bash
aegis ai agents add <slug> options
OptionDefaultMeaning
--nameslugdisplay name
--description""one line about the agent
--kindsub-agentmaster, sub-agent or utility
--model"" (config default)model slug
--max-steps25provider hops one turn may make (1–200)
--instructions-file""read the instructions from this file
--paralleloffallow sub-agents and tools to run concurrently
bash
aegis ai agents add helper --name "Helper" --model deepseek-flashaegis ai agents add auditor --kind utility --max-steps 8 --instructions-file notes.md
text
✔ helper: agent added

A taken slug, an unknown kind or an unknown model exits 1 with the reason; an unreadable --instructions-file prints ✖ cannot read the instructions: [Errno 2] No such file or directory: 'notes.md'.

#aegis ai agents edit

Change the fields that were passed on an agent the command line owns. Anything omitted keeps its value. An agent that comes from a file is refused, with the path to edit instead.

bash
aegis ai agents edit <slug> options
OptionDefaultMeaning
--nameunchangeddisplay name
--descriptionunchangedone line about the agent
--kindunchangedmaster, sub-agent or utility
--modelunchangedmodel slug
--max-stepsunchangedprovider hops one turn may make
--instructions-file""replace the instructions from this file
--parallelunchangedallow concurrency
--no-parallelunchangedforbid concurrency
bash
aegis ai agents edit helper --max-steps 15aegis ai agents edit helper --no-parallel --model deepseek-v4-pro
text
✔ helper: agent updated

Passing nothing that changes a field exits 1 with ✖ nothing to change.

#aegis ai agents remove

Destructive. The row is deleted. On a system agent the command refuses; on an agent created here the deletion is immediate and there is no undo.

Delete an agent the command line owns. Its attachment rows go with it. A file-owned agent cannot be removed here: remove the directory under storage/ai/agents/ and run aegis ai setup.

bash
aegis ai agents remove <slug>
ArgumentDefaultMeaning
slugrequiredagent to delete
bash
aegis ai agents remove helperaegis ai agents remove auditor
text
✔ helper: agent removed
text
✖ this agent comes from /aegis/storage/ai/agents/aegis/agent.md; remove the file  and run `aegis ai setup`

#aegis ai agents tools

List the tools attached to an agent, with optional attachments and detachments in the same call. --add takes a pattern: shell.* for a whole pack, or one name such as files.read. The final table is always the state after the changes, so it doubles as a check.

bash
aegis ai agents tools <slug> --add <pattern> --remove <name>
OptionDefaultMeaning
--addnoneattach every tool the pattern matches; repeatable
--removenonedetach this exact tool name; repeatable
bash
aegis ai agents tools aegisaegis ai agents tools aegis --add 'shell.*' --remove web.fetch
text
tool          pack   status────────────  ─────  ──────shell.ps      shell  activeshell.run     shell  activefiles.read    files  active

A pattern that matches nothing prints ⚠ nothing matched: shell.*; a name that was not attached prints ⚠ not attached: web.fetch. Both are warnings, and the command still exits 0.

#aegis ai agents skills

List the skills an agent carries, with the same --add/--remove shape as tools. --add accepts a slug (conventions) or a category pattern (aegis/*).

bash
aegis ai agents skills <slug> --add <pattern> --remove <slug>
OptionDefaultMeaning
--addnoneattach every skill the pattern matches; repeatable
--removenonedetach this exact skill slug; repeatable
bash
aegis ai agents skills aegisaegis ai agents skills scout --add troubleshooting
text
skill              name                category─────────────────  ──────────────────  ────────platform-overview  Platform overview   aegistroubleshooting    Troubleshooting     aegis

#aegis ai agents subagents

List the agents one agent may delegate to, and change that list. Only an attached agent can be called with agents.call; recursion is capped at two levels by the engine.

bash
aegis ai agents subagents <slug> --add <slug> --remove <slug>
OptionDefaultMeaning
--addnoneattach this agent as a sub-agent; repeatable
--removenonedetach this sub-agent; repeatable
bash
aegis ai agents subagents aegisaegis ai agents subagents helper --add scout --add aegis
text
agent  name   kind─────  ─────  ─────────scout  Scout  sub-agent

#Tools

A tool is a Python class with a ToolSpec. The catalogue row mirrors that spec: a sync writes it, and a row can disable a tool but never change what it does. Tools are grouped in packs (shell, files, aegis, …), which is also the unit a turn loads.

#aegis ai tools list

Print the tools grouped by pack, or one plain table when --pack names a pack. Columns are the tool name, whether it mutates the host, its status and its timeout.

bash
aegis ai tools list --pack <pack> --all
OptionDefaultMeaning
--pack"" (all packs)only this pack; prints one ungrouped table
--alloffinclude disabled and archived tools
bash
aegis ai tools listaegis ai tools list --pack shell
text
tool              mutator  status  timeout────────────────  ───────  ──────  ───────aegis/aegis.command              active  120saegis.docs_read            active  30sshell/shell.ps                   active  30sshell.run         yes      active  120s

The pack-filtered form:

text
tool       mutator  status  timeout─────────  ───────  ──────  ───────shell.ps            active  30sshell.run  yes      active  120s

#aegis ai tools show

Print one tool as a key/value block, then its description, when to use it, and the parameter schema as JSON. declared says whether the module that defines the tool still exists in this build.

bash
aegis ai tools show <name>
ArgumentDefaultMeaning
namerequiredtool name, for example files.read
bash
aegis ai tools show files.readaegis ai tools show shell.run
text
name        files.readpack        filesstatus      activemutator     noconcurrency paralleltimeout     30sdeclared    yesRead a text file from the project tree, with an optional line range. The path is relative to the project root.When: When you know which file holds the answer.[  {    "name": "path",    "type": "string",    "description": "Path relative to the project root."  },  {    "name": "start",    "type": "integer",    "description": "First line, 1-based.",    "default": 1  }]

#aegis ai tools enable

Put a tool back in active state so agents that carry it are offered it again. The change survives the next sync.

bash
aegis ai tools enable <name>
ArgumentDefaultMeaning
namerequiredtool name
bash
aegis ai tools enable shell.runaegis ai tools enable files.write
text
✔ shell.run: active

#aegis ai tools disable

Stop offering a tool to the model while keeping its row and its attachments. This is the safe way to remove a dangerous capability without editing any agent file. It is reversible with enable.

bash
aegis ai tools disable <name>
ArgumentDefaultMeaning
namerequiredtool name
bash
aegis ai tools disable shell.runaegis ai tools disable files.write
text
✔ shell.run: disabled

#aegis ai tools sync

Write every tool declaration into ai.db. The status column is preserved, and a tool whose module disappeared is archived rather than deleted.

bash
aegis ai tools sync
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis ai tools syncaegis ai tools sync && aegis ai tools list
text
✔ 41 tools in 12 packs

When a row was archived, the line ends with the count:

text
⚠ 1 tool(s) archived: their module is gone✔ 41 tools in 12 packs, 1 archived

#Skills

A skill is a prompt block an agent carries. Skills that ship with the platform live as storage/ai/skills/<category>/<slug>/skill.md with a TOML header between +++ lines; those are read-only here. Skills created with add have no file and are owned by the command line.

#aegis ai skills list

Print the skills with their category, type, body size and status.

bash
aegis ai skills list --category <name> --all
OptionDefaultMeaning
--category"" (all)only this category
--alloffinclude archived skills
bash
aegis ai skills listaegis ai skills list --category aegis
text
slug               name                  category  type         chars  status─────────────────  ────────────────────  ────────  ───────────  ─────  ──────ai                 AI module             aegis     reference    6120   activebind               BIND and DNS          aegis     reference    4821   activeconventions        Project conventions   aegis     instruction  3890   activeplatform-overview  Platform overview     aegis     reference    5210   active

The valid types are instruction, prompt, reference, template, workflow and other.

#aegis ai skills show

Print one skill's metadata and then its body, unchanged.

bash
aegis ai skills show <slug>
ArgumentDefaultMeaning
slugrequiredskill slug
bash
aegis ai skills show conventionsaegis ai skills show platform-overview
text
slug        conventionsname        Project conventionscategory    aegistype        instructiontags        rules, style, processversion     1.0.0status      activesource      /aegis/storage/ai/skills/aegis/conventions/skill.md# ConventionsThese are not suggestions; a change that breaks one is sent back.## Code- Python 3.12. `X | None`, built-in generics, `from __future__ import  annotations` where it helps.

#aegis ai skills add

Create a skill that has no file. A body is required: pass it inline with --content or read it from a file with --file.

bash
aegis ai skills add <slug> options
OptionDefaultMeaning
--nameslugdisplay name
--category""grouping label, for example aegis
--description""one line about the skill
--typeinstructionone of the six skill types
--file""read the body from this file
--content""the body, inline
bash
aegis ai skills add house-style --name "House style" --file notes.mdaegis ai skills add on-call --category ops --content "Escalate to the on-call rota."
text
✔ house-style: skill added (1840 chars)

With neither --file nor --content:

text
✖ a skill needs a body: pass --file or --content

#aegis ai skills edit

Change the fields that were passed on a skill the command line owns. There is no --category here: a skill's category is fixed at creation. A file-owned skill is refused with the path to edit.

bash
aegis ai skills edit <slug> options
OptionDefaultMeaning
--nameunchangeddisplay name
--descriptionunchangedone line about the skill
--typeunchangedone of the six skill types
--file""replace the body from this file
--content""replace the body inline
bash
aegis ai skills edit house-style --file notes.mdaegis ai skills edit on-call --type workflow
text
✔ house-style: skill updated

#aegis ai skills remove

Destructive. The row is deleted, and there is no undo. A skill that comes from a file is refused: delete the directory and sync instead.

Delete a skill the command line owns.

bash
aegis ai skills remove <slug>
ArgumentDefaultMeaning
slugrequiredskill to delete
bash
aegis ai skills remove house-styleaegis ai skills remove on-call
text
✔ house-style: skill removed

#aegis ai skills sync

Import every skill.md under storage/ai/skills into the catalogue. A changed file updates its row, an unchanged one is left alone, a file that disappeared archives its row. Rows with no file are never touched.

bash
aegis ai skills sync --root <directory>
OptionDefaultMeaning
--rootstorage/ai/skillsimport from another directory instead
bash
aegis ai skills syncaegis ai skills sync --root /tmp/skills
text
✔ 2 created, 1 updated, 7 unchanged, 0 archived

#Chats

#aegis ai chat

Open a conversation in the plain terminal: a line in, a streamed answer out, a prompt again. It is a read-eval-print loop, not a full-screen application, so it works over any SSH session. The banner names the agent, the model and the chat; /help lists the commands below.

bash
aegis ai chat --agent <slug> --chat <uuid> --model <slug>              --no-stream --max-steps <n>
OptionDefaultMeaning
--agentai.default_agent (usually aegis)agent for a new chat
--chat""continue this chat instead of opening one
--modelthe agent's modelmodel for a new chat
--no-streamoffone request per hop, no streamed text
--max-steps0hops per turn; 0 means the agent's own limit

--agent and --model only apply when the command opens a chat; with --chat they are ignored and the chat's own agent and model are used.

bash
aegis ai chataegis ai chat --chat 629a26dc16ad4a8ea68240705cb60654aegis ai chat --agent aegis --model deepseek-flash --no-stream
text
Aegis chat · agent aegis · model deepseek-flashchat 629a26dc16ad4a8ea68240705cb60654/help for commands · Ctrl-D to leave› ce servicii sunt oprite?  · Run aegis status 574msNu este oprit niciun serviciu: keeper, panel, pulse și bird rulează.1 step(s) · 1 tool(s) · 8142/126 tokens · $0.0018›

An unknown chat exits 1:

text
✖ unknown chat: 629a26dc

An unknown agent exits 1 with a pointer to setup:

text
✖ unknown agent: helper; run `aegis ai setup`

A turn that fails prints the message after ✖; a turn stopped by the operator prints ℹ stopped, and the transcript stays readable.

#The chat REPL

Lines starting with / are commands for the shell around the chat. Anything else is a prompt for the agent, in the same chat, until you leave. Every command prints its answer and returns to the prompt.

#/help

Print the command list.

bash
/help
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/help
text
Commands  /help              this list  /new               start a new chat  /sessions [n]      list chats, or switch to one by number or UUID  /chat              the UUID of this chat  /model [slug]      show or change the model of this chat  /context           how full the window is  /compact           fold the older messages into a summary  /tools             what this agent can call  /quit              leave (Ctrl-D does the same)

#/new

Start a new chat on the same agent and model. The old chat stays in the database; the banner prints the new UUID.

bash
/new
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/new
text
Aegis chat · agent aegis · model deepseek-flashchat 6f1c0b2e9a7d4c0f8b3e5d6a1c2b3d4e/help for commands · Ctrl-D to leave

#/sessions

List the last twenty chats, newest first, or switch to one by its list number or a UUID prefix. A switch reloads the agent, the model and the transcript.

bash
/sessions n|prefix
ArgumentDefaultMeaning
n / prefixnone (list only)list number or UUID prefix to switch to
bash
/sessions/sessions 3/sessions 629a26dc
text
#  chat      agent  messages  updated─  ────────  ─────  ────────  ───────────────────1  6f1c0b2e  aegis  12        2026-11-17 06:41:022  629a26dc  aegis  48        2026-11-17 06:12:443  2b7e55aa  scout  6         2026-11-16 22:07:19  /sessions <n> to switch
text
ℹ switched to 2b7e55aa8c1d4e0f9a6b5c4d3e2f1a0b
text
✖ no session matches 99

#/chat

Print the UUID of the open chat, which is the value --chat and the panel expect.

bash
/chat
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/chat
text
629a26dc16ad4a8ea68240705cb60654

#/model

Show the model of the open chat, or change it for the rest of the conversation. The change is written to the chat row, so it survives a reconnect.

bash
/model slug
ArgumentDefaultMeaning
slugnone (show only)model slug to switch to
bash
/model/model deepseek-v4-pro
text
deepseek-flash
text
ℹ model: deepseek-v4-pro
text
✖ unknown model: gpt-9

#/context

Print how full the window is, how many messages a fold always keeps, and how much text the current summary holds.

bash
/context
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/context
text
24118 / 1000000 tokens (2.4%) · keep_last 6 · summary 0 chars

#/compact

Fold the older messages now, with the model writing the summary. It keeps the last compact_keep_recent messages verbatim and stores the summary on the chat; the transcript rows are not rewritten.

bash
/compact
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/compact/compact
text
ℹ folding 34 messages…ℹ summary 5120 chars · until message 18

When there is nothing old enough to fold:

text
ℹ nothing older than the kept tail; no fold needed

#/tools

Print what the open chat's agent can call, grouped by pack with a count per pack.

bash
/tools
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/tools
text
aegis (6)  aegis.command, aegis.docs_read, aegis.docs_search, aegis.info, aegis.services, aegis.tasksshell (2)  shell.ps, shell.run

A chat with no agent prints ℹ this chat has no agent; an agent with nothing attached prints ℹ no tool attached.

#/quit

Leave the chat. /exit and /q are accepted aliases, and Ctrl-D does the same.

bash
/quit
Argument / optionDefaultMeaning
——none; the command takes no arguments
bash
/quit/exit

No output beyond the shell prompt returning.

#Keys

KeyAt the promptDuring a turn
Entersend the line—
Ctrl-Dleave the chat—
Ctrl-Cclear the linemark the turn interrupted and return to the prompt
Escape twice within 1.2 s—ask the turn to stop between hops
↑ / ↓history, when the readline module is present—

A question from interact.* is printed inline; numbered options are offered when the tool declared them, and typing the number selects that option. The question is answered on the terminal, and the answer becomes the tool result.

#One-shot prompts

#aegis ai prompt

Run exactly one turn and print the answer. Without --chat it opens a chat and prints its UUID on the last line; with --chat it continues that conversation. Streaming is the default: text arrives as the provider writes it, tool calls print as they run, and the final line carries the chat and the counters.

prompt locks the interaction pack: a one-shot run cannot ask you a question. Use aegis ai chat when the agent may need an answer.

bash
aegis ai prompt <text> --agent <slug> --chat <uuid> --model <slug>                --no-stream --json --max-steps <n> --background
OptionDefaultMeaning
textrequiredthe prompt; several words are joined with spaces
--agentai.default_agentagent for a new chat
--chat""continue this chat
--modelthe agent's modelmodel for a new chat
--no-streamoffone request, print the final text once
--jsonoffprint one JSON object and nothing while it runs
--max-steps0hops for this turn; 0 means the agent's own
--backgroundoffqueue the turn for the daemon and return

--agent and --model only apply when a new chat is opened; with --chat the existing chat's agent and model are used.

bash
aegis ai prompt "ce servicii sunt oprite?" --agent aegisaegis ai prompt --chat 629a26dc16ad4a8ea68240705cb60654 "și câte sunt în total?"aegis ai prompt "spune ok" --no-streamaegis ai prompt --json "spune ok"
text
Serviciile oprite sunt: niciunul. Keeper, panel, pulse și bird rulează.ℹ chat 629a26dc16ad4a8ea68240705cb60654 · 2 steps · 1 tools · 8142/126 tokens · $0.0018

With --json, one object on stdout:

text
{"ok": true, "chat": "629a26dc16ad4a8ea68240705cb60654", "turn": 6, "status": "done", "content": "ok", "steps": 1, "tool_calls": 0, "input_tokens": 3937, "output_tokens": 2, "cost": 0.000592, "error": ""}

aegis --json ai prompt … is the same as --json. In JSON mode a failed turn still prints the object; the exit code is 1.

An empty prompt exits 1 with ✖ nothing to ask. A missing key fails before anything is spent:

text
✖ no api key for deepseek; run `aegis ai providers set-key deepseek`

Ctrl-C during the turn marks it interrupted, exactly like the chat.

#Queuing the turn

With --background the command stores a turn and returns at once; the aegis-ai daemon claims it. It prints the new turn id and the chat UUID:

bash
aegis ai prompt --background "cât e ceasul?"
text
✔ turn 42 queued for chat 629a26dc16ad4a8ea68240705cb60654

With --json the same call emits:

text
{"ok": true, "turn": 42, "chat": "629a26dc16ad4a8ea68240705cb60654", "status": "queued"}

Follow the turn with aegis ai jobs list, or read its row with aegis ai jobs show 42.

#Background work

A background turn is a row in ai_turns with status = 'queued'. The daemon claims turns with a conditional update — one per worker, up to [ai] max_turns — runs each with the same engine as a foreground prompt, and publishes every event on the Bird topic ai. A turn that needs an answer goes waiting until aegis ai answer fills the question or the interaction timeout expires.

#aegis ai jobs list

Print the most recent turns, newest first, with the chat (short UUID), agent, status, counters, cost and start time.

bash
aegis ai jobs list --limit <n>
OptionDefaultMeaning
--limit20how many turns to print
bash
aegis ai jobs listaegis ai jobs list --limit 5
text
id  chat      agent   status  steps  tools  cost     started──  ────────  ──────  ──────  ─────  ─────  ───────  ───────────────────42  629a26dc  aegis   done    3      4      $0.0041  2026-11-17 06:40:1241  6f1c0b2e  scout   done    1      2      $0.0007  2026-11-17 06:32:5540  2b7e55aa  aegis   failed  0      0      $0.0000  2026-11-17 06:20:03

An empty queue prints ℹ no turn yet.

#aegis ai jobs show

Print one turn: its counters, its error, then the prompt (first 600 characters) and, when the turn is waiting, the questions nobody answered.

bash
aegis ai jobs show <id>
ArgumentDefaultMeaning
idrequirednumeric turn id from jobs list
bash
aegis ai jobs show 42aegis ai jobs show 17
text
turn    42chat    1183origin  clistatus  donesteps   3tools   4tokens  9120/310cost    $0.0041error   —care e starea serviciilor?question                   type     uuid─────────────────────────  ───────  ────────────────────────────────May I restart nginx?       confirm  a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d

An unknown id prints ✖ unknown turn: 42 and exits 1.

#aegis ai jobs cancel

Destructive. A queued turn is marked cancelled and will never run; a running turn is asked to stop between hops, so its partial transcript stays. Neither kills a process.

Drop a queued turn, or ask a running or waiting one to stop.

bash
aegis ai jobs cancel <id>
ArgumentDefaultMeaning
idrequirednumeric turn id
bash
aegis ai jobs cancel 42aegis ai jobs cancel 17
text
✔ turn 42: dropped from the queue
text
✔ turn 17: stop requested

A finished turn cannot be cancelled:

text
✖ turn 12 is done, nothing to cancel

#aegis ai answer

List the questions nobody answered, or answer one. Without a UUID it prints the pending table; with one it stores the text and the waiting worker continues.

bash
aegis ai answer uuid --text <answer>
ArgumentDefaultMeaning
uuid"" (list only)question UUID, or its numeric id
--text""the answer; asked for on the terminal when omitted
bash
aegis ai answeraegis ai answer a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d --text "yes"
text
uuid                              type     question              asked────────────────────────────────  ───────  ────────────────────  ───────────────────a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d  confirm  May I restart nginx?  2026-11-17 06:40:31
text
✔ answered: a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d

Without a pending question the listing says ℹ no pending question. An unknown or already answered question exits 1:

text
✖ that question is answered

#aegis ai daemon

Run the background worker in the foreground. The keeper starts it as the service aegis-ai; use this command to watch it, or to run it once by hand.

bash
aegis ai daemon
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis ai daemonaegis keeper services
text
1 turn(s) interrupted by the previous processready: 2 worker(s), poll 1.5sturn 42 done: 3 steps, 4 tools, $0.0041turn 43 failed: 0 steps, 0 tools, $0.0000 — HTTP 401

The daemon takes an exclusive lock in run/ai.lock, writes run/ai.pid, and rewrites run/ai.heartbeat while it runs, so the keeper can tell a frozen process from a working one. A second copy logs already running (pid 802341) and exits 0. A turn left running by a dead process is marked interrupted at start — never resumed, because half its transcript already exists.

Set [ai] daemon = false (or ai.enabled = false) to keep this host out of the queue entirely; [ai] max_turns and [ai] poll tune the workers.

#Reading a turn's outcome

Every command that runs a turn reports the same statuses, and jobs list shows them in the status column:

StatusMeaning
queuedwaiting for the daemon
runninga worker holds it
waitingstopped on a question (interact.*)
donethe model returned a final answer
faileda provider or tool error; error holds the message
cancelledthe operator asked it to stop
interruptedCtrl-C, or a dead process's turn recovered at daemon start
max_stepsthe hop limit was reached; stored as failed

The footer of prompt and chat is the same shape everywhere, with the values of that turn:

text
ℹ chat 629a26dc16ad4a8ea68240705cb60654 · 2 steps · 1 tools · 8142/126 tokens · $0.0018

#Configuration

All keys live under [ai] in config/ai.toml (the file is merged with every other config/*.toml by load_server()).

KeyDefaultMeaning
default_agentaegisagent when a command names none
default_providerdeepseekprovider used when a chat names none
default_modeldeepseek-flashmodel for an agent without one
max_turns2background turns run at once
max_steps25provider hops one turn may make
parallel_agents4concurrent sub-agents
parallel_tools4concurrent tool calls
toolboxtrueoffer the loading gate instead of every schema
shell_confirmtrueconfirm a mutating tool before it runs
interaction_timeout600seconds a turn waits for an answer
request_timeout300seconds one provider request may take
compact_autotruefold before the window fills
compact_threshold0.80share of the window that triggers a fold
compact_keep_recent6messages a fold always keeps verbatim
compact_keep_tokens15000tokens of the tail the fold must not touch
compact_buffer16000room kept free below the window
daemontruerun aegis-ai on this host
enabledtrueswitch the module off entirely

Provider credentials live in [providers.<slug>]: name, driver, auth_type, api_url, api_key, is_default and status. The database row written by set-key wins over api_key here; a sync never copies the config key into the row, so clearing the row restores the fallback.

#Exit codes

CodeWhen
0the command did what it was asked, including a listing that found nothing
1an unknown slug or id, a missing key, a refused edit, a failed prompt
2the line itself was wrong: unknown command, missing argument
130the root command was interrupted

The commands themselves never ask "are you sure"; the destructive ones are marked above. The only prompts are the secret set-key reads, the answer answer reads when --text is omitted, and the questions a chat turn asks through the interact.* tools.