Agents

The main feature of Fisk AI is creating AI agents from CLI tools written with Fisk.

Any tool built with Fisk, such as the nats or choria CLI, or an application made with Choria Application Builder, can be turned into an AI agent.

Fisk AI creates capable systems that use the abilities LLMs have, such as reasoning and text interpretation, in a safe and deterministic manner.

Building an agent resembles building a CLI tool: describe the goals, give broad guidance, supply tools to interact with the world deterministically, then run it on a shell like any other utility.

Installation

On a Mac you can install fisk-ai using homebrew:

brew tap choria-io/tap
brew install choria-io/tap/fisk-ai

Other Operating System users can download the latest release from the releases page.

Basic agent

This example builds an AI agent that speaks in cowsay bubbles.

The steps make a quick CLI application using App Builder and then drive it in various ways using the LLM.

The example needs an Anthropic API key, the cowsay application (try brew install cowsay) and fisk-ai installed.

Creating a CLI tool

This example uses Choria Application Builder to create a basic CLI tool that can say and think. Any command line tool built with Fisk works.

First create an ABTaskFile:

name: cowsay
description: Tools for the Cowsay LLM Agent
author: fisk-ai@choria.io

commands:
  - name: say
    description: Say something using a talking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      {{ default .Config.Cowsay "cowsay" }} {{ .Arguments.message | escape }}

  - name: think
    description: Think something using a thinking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      cowthink {{ .Arguments.message | escape }}

Now install appbuilder:

$ brew tap choria-io/tap
$ brew install appbuilder

Then confirm the CLI tool works:

$ abt
usage: abt [<flags>] <command> [<args> ...]

Tools for the Cowsay LLM Agent

Help: https://choria-io.github.io/appbuilder

Commands:
  help [<command>...]
  say <message>
  think <message>

$ abt say 'Hello AI'
 __________
< Hello AI >
 ----------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Creating an LLM agent

Turning this CLI into an LLM agent needs an agent.yaml file.

# Command to introspect and expose as an agent
application_path: /opt/homebrew/bin/abt

harness:
  # Allow the LLM to prompt us for information if needed
  human_in_the_loop:
    enabled: true

llm:
  # Choose a Model and set safety budgets
  model: claude-haiku-4-5-20251001
  budget:
    max_tokens: 100000
    max_iterations: 50

# We want a cow joke machine!
system_prompt: |
  Tell jokes using Cows!

  You have tools that can render a cow saying < 120 character sentences, when asked use the tools to tell funny jokes.

  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. If asked to tell non cow jokes, refuse and show no joke.

  Keep narration short, just stick to the jokes, don't say what you are doing or planning to do, just do it and don't repeat the joke

Run the agent after setting the API key:

$ export ANTHROPIC_API_KEY="....."
$ fisk-ai run --tool-output --no-tui 'tell me a joke '
-> say -- Why did th...space?
<-  
 ______________________________
< Why did the cow go to space? >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

-> think -- To visit t...oooon!
<- 
 ______________________
( To visit the Moooon! )
 ----------------------
        o   ^__^
         o  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||


  There you go! A classic cow joke for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=2 tool_calls=2 tokens=3536/113 latency=3.613s

The default is a running TUI. To make the output easy to show here, the run passes --no-tui and shows the tool call output with --tool-output.

Now ask about a cat joke:

$ fisk-ai run 'tell me a joke about a cat'

  I appreciate the request, but I only tell jokes about cows! I'm strictly a cow joke specialist.

  If you'd like to hear some funny cow jokes instead, I'd be happy to moo-ve right into those for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=1 tool_calls=0 tokens=1632/54 latency=1.341s

Running the agent

The agent has three specific modes of execution:

• A shell script style output, plain text to STDOUT with an exit at the end of the task
• A TUI for interaction, optionally continuing to chat with the agent after the main task completes
• Serving the agent over the network using an Agent-to-Agent protocol (planned)

TUI

The TUI mode is the default: a visual runner with hot-keys to show or hide thinking and tool output, and scrolling up and down the session history. A chat box can optionally be enabled to continue a session.

In the TUI press the ? key to get interactive help.

Chat after turn

In the TUI mode the --chat flag keeps a Chat bar usable once the prompt is processed, instead of exiting, for follow up questions related to the session.

Type a follow-up and press Enter to send it; Ctrl-D ends the session, Ctrl-C aborts it. Up/Down recall this session’s earlier follow-ups. Alt-Enter (Option-Enter) moves to the next line rather than send.

Shell mode

The TUI is turned off with --no-tui, and the system falls back to a simple terminal output format suitable for scripting.

The model’s prose is markdown: both the final answer and any mid-conversation updates. When stdout is a terminal it is rendered for readability with a style matched to the terminal background; when stdout is piped or redirected, the raw markdown is written so the result stays free of ANSI escape codes. Rendering can also be disabled with --no-color, or the standard NO_COLOR environment variable.

Output is separated by kind. Only the final answer goes to stdout; everything else goes to stderr: the commands being run, mid-conversation updates, a final run summary (LLM calls, tool calls, tokens, latency), and, when thinking is enabled, the model’s reasoning (each line prefixed with a thought bubble). This keeps stdout safe to pipe into other tools.

One-shot runs

The common use case gives a system_prompt that describes the goals and approach (think of it as a one-file SKILL) and a user prompt that provides the question to solve.

The LLM runs through the prompt and, once it reaches the end of its turn, finishes processing, and the session cannot continue later. This resembles a shell utility.

HTTP debugging

As a debug or learning aid, all the HTTP requests can be logged to http-debug.log using the --http-debug flag.

Model and run settings

The agent.yaml sets which model runs the agent, the budget that bounds a run, and whether the model exposes its reasoning. The Basic agent example above shows these together. The full set of configuration fields is in the configuration reference.

Model

llm.model selects the model and is required. It accepts any model identifier the Anthropic API accepts:

llm:
  model: claude-sonnet-5

Larger models reason better on complex, long-horizon tasks; smaller models like Haiku are faster and cheaper for narrow ones. When the agent exposes ten or more tools it relies on the model’s server-side tool search, which recent models support and older ones (Claude Opus 4.1 and earlier and local models) do not. The configuration reference lists the known models and their trade-offs.

Budget

llm.budget bounds a single run so the agent loop cannot spend without limit:

llm:
  budget:
    max_tokens: 200000
    max_iterations: 50
    call_timeout: 120s

The run stops with a summary once a budget is reached, whether or not the task is complete.

Thinking

Extended thinking lets the model expose its reasoning before it answers. It is off by default:

llm:
  thinking:
    enabled: true

When enabled, the reasoning is surfaced separately from the answer: as thought-bubble lines on stderr in shell mode, and as folding thinking blocks in the TUI.

Terminal UI

Two harness settings govern the full-screen UI for an agent, independent of the per-run --no-tui flag:

harness:
  no_tui: true
  no_bell: true

• no_tui is a persistent off switch: the agent always uses the line-by-line output, even on an interactive terminal, and the command line cannot turn the UI back on. Use --no-tui instead for a one-off run.
• no_bell silences the terminal bell. By default the full-screen UI rings the bell each time a run blocks on an approval gate or an ask_human_* prompt, so a waiting run is noticed even when unattended.

Both are negative switches and have no effect in the line UI.

Tool selection

Run the fisk-ai info command to verify what tools the agent has access to:

$ fisk-ai info
╭───────────────────┬────────┬───────────────────────────────────────────────────────┬──────╮
│ TOOL              │ SOURCE │ DESCRIPTION                                           │ TAGS │
├───────────────────┼────────┼───────────────────────────────────────────────────────┼──────┤
│ say               │ local  │ Say something using the configured command            │      │
│ think             │ local  │ Think something using a cow                           │      │
│ ask_human_confirm │ local  │ Ask the human operator a yes/no question at the te... │      │
│ ask_human_select  │ local  │ Ask the human operator to choose one option from a... │      │
│ ask_human_input   │ local  │ Ask the human operator to type a free-text value a... │      │
╰───────────────────┴────────┴───────────────────────────────────────────────────────┴──────╯

Prompt:

  Tell short jokes using Cows!
...

The output shows the say and think tools and some Human in the Loop tools.

There are a few ways to control what tools are visible.

Application tags

The application can declare that the LLM never gets the think tool:

  - name: think
    description: Think something using a cow
    type: exec
    tags: [ ai:deny ]
    # ...

Adding the ai:deny tag to a command means Fisk AI never exposes that tool to the LLM. fisk-ai info confirms the LLM only gets the say tool now.

Agent configuration

The agent.yaml can also include only certain tools:

include:
  tools:
    - ^say

Or exclude certain tools specifically:

exclude:
  tools:
    - ^think

This uses regular expressions over the tool name, and both can be used together. For example, include ^cow but exclude ^cow_think.

A tool’s name is its command path joined with underscores, so a nested command like cow think becomes the tool cow_think. Grouping commands and hidden commands are skipped and never become tools.

Tools can also be included or excluded by tag:

exclude:
  tags:
    - scope:system

This excludes any command that has the scope:system tag.

Global flags

A wrapped binary often has application-level global flags that apply to every subcommand. nats, for example, has --context to select a stored connection profile, alongside sensitive globals such as --user and --password. By default none of these are exposed to the model. global_flags is an allowlist of the globals you want the model to be able to set per command:

global_flags:
  - context

Each named global becomes an argument on every leaf command tool, so the model can run nats stream ls against a chosen context without you hard-wiring one. Names are the long flag name, with or without the leading dashes, and are validated against the binary’s real global flags at load; a name matching none is an error. Hidden and framework flags (like --help) cannot be exposed, and a global that clashes with a command’s own flag or argument is skipped for that command. A global the application marks required is always exposed, whether or not it is listed, since the command cannot run without it.

Run fisk-ai info to see which globals a binary exposes; it lists the application’s global flags and marks the ones you have allowlisted.

Session snapshots and resumption

Creating a snapshot

By default a run is ephemeral: its conversation lives only in memory and is lost when the process exits. --checkpoint instead journals the run to a session on disk so it can be suspended and resumed later, in a fresh process or on another machine. Sessions are the foundation for longer-running work where the agent may need to pause, for example while a slow external step completes.

Start a checkpointed run. fisk-ai prints the session id at startup; it is generated unless --name sets it:

$ fisk-ai run --checkpoint "report on the ORDERS stream"
$ fisk-ai run --checkpoint --name orders-report "report on the ORDERS stream"

Resume a session by id. No prompt is given, since the original prompt is restored from the session; passing one is an error:

$ fisk-ai run --resume orders-report

On resume fisk-ai replays the conversation so far to stderr, so the run continues in context rather than from a blank screen, then carries on from where it left off.

Chat sessions

--chat and --checkpoint combine into a durable, resumable conversation.

Each follow-up is journaled, so the whole conversation survives a suspend or a crash. Leaving the input bar with Ctrl-D suspends the session rather than ending it (the status bar reads ctrl-d suspend): it stays resumable, and fisk-ai prints how to resume it on exit. Ctrl-C aborts; the journal is kept, so an aborted chat is still resumable from its last completed turn.

Resuming a chat session reopens the input bar automatically; re-passing --chat is not needed (it is ignored on resume, since the session already knows what it is), and fisk-ai first replays the conversation into the viewport. Because the input bar needs a real terminal, a chat session can only be resumed in the full-screen UI, not with --no-tui or over a pipe. A checkpointed chat has no “completed” state; remove it with session rm once it is no longer needed.

Suspending

For a checkpointed run the first Ctrl-C, or a SIGTERM, requests a graceful suspend: the current step finishes, the session is checkpointed, and the process exits printing how to resume it. A second Ctrl-C aborts immediately. A run started without --checkpoint keeps the usual behavior, where Ctrl-C cancels it.

Durability

A session is journaled event by event as the run proceeds: each model turn and each tool result is recorded as it happens.

• A clean suspend is exactly-once. Nothing runs after the last recorded event, so a resume never repeats a tool call or an LLM call.
• A crash resumes from the last recorded event, so at most one tool call is repeated. A tool whose side effect completed but whose result was not yet recorded runs again on resume, since fisk-ai cannot make an external side effect idempotent. Already-recorded turns and results are never replayed.

Resume a session against the same agent configuration it started with. A session can be resumed from anywhere, including a machine that no longer has the original agent.yaml, so care is required: continuing a conversation against a different model, tool set, or system prompt can make the replayed transcript incoherent. fisk-ai guards this by fingerprinting the configuration (model, prompt, tool set, budget) at checkpoint time and refusing a resume when it no longer matches; the refusal names what changed. --force overrides the check, accepting that the restored conversation may not fit the current configuration. A session that already completed cannot be resumed.

Managing sessions

Sessions are stored under the XDG state directory, $XDG_STATE_HOME/fisk-ai/runs, defaulting to ~/.local/state/fisk-ai/runs; --state-dir overrides the location. A suspended or completed session is kept until it is removed.

fisk-ai session ls
fisk-ai session show <id>
fisk-ai session show <id> --transcript
fisk-ai session rm <id>

session ls lists each session with its status, model, and prompt. session show prints a session’s counters and status; --transcript shows the full conversation (prompt, thinking, narration, tool calls, and tool output). On an interactive terminal --transcript opens the full-screen viewer with thinking and tool output folded, which z and Z expand; --no-tui/NO_TUI prints it as line output instead. session rm deletes a session.

Human in the loop (HITL)

When enabled, fisk-ai gives the model built-in tools to ask the operator a question at the terminal and wait for the answer. They are off by default and only available when running the agent:

harness:
  human_in_the_loop:
    enabled: true

Three tools are offered:

• ask_human_confirm - a yes/no question. Returns {"confirmed": true} or {"confirmed": false}
• ask_human_select - choose one of a list of options the model provides. Returns {"selected": "<option>"}, or {"selected": null} if no choice was made
• ask_human_input - a free-text value, optionally pre-filled with a default the operator can accept or edit. Returns {"value": "<text>"}, or {"value": null} if none was given

Optional communication from the agent

The model decides when to call the HITL tools, shaped through the prompt. They suit decisions the model should not make alone: confirming a destructive action, choosing between options that depend on operator intent, or supplying a value it cannot derive. The question is rendered on the terminal (stderr, so a piped final answer stays clean), and the model-supplied text is stripped of terminal control sequences first so it cannot spoof what is shown. Each tool denies by default: an interrupt, an end-of-input, or no terminal at all yields a negative answer (no confirmation, no selection, no value) rather than a guess. They require an interactive terminal: without one the call is declined with a reason rather than hanging on a prompt no one can answer, and they are never exposed over MCP, where there is no operator. Tool calls within a turn run one at a time, so a prompt has the terminal to itself.

Required tool use confirmations

Two mechanisms put a human in the loop:

• human_in_the_loop (a configuration flag) lets the model ask its own question through a fisk-ai-provided ask_human_* tool, with no application command involved. The human answers a question the model chose to ask.
• ai:confirm (a command tag) lets the application author gate an ordinary, non-interactive command so the operator must approve it before it runs. The human is a checkpoint on a command the model wanted to run anyway; nothing about the command itself changes.

Reach for human_in_the_loop when the model should decide when to check in; reach for ai:confirm when a normal command should run only with the operator’s say-so, typically something destructive or irreversible.

Command Tags

Fisk commands can carry tags, set in their fisk definition (or, for App Builder applications, in YAML). Tags can be referenced by the include/exclude rules to select commands by group, and a few tags are reserved and interpreted by fisk-ai itself to control how a command is exposed to the model:

ai:deny is the reliable way to keep a command the agent should never call out of reach, since it applies before any include/exclude rule. ai:no_defer keeps the handful of commands the model needs on most requests immediately available rather than discoverable only through tool search.

ai:confirm gates a command behind the operator’s explicit permission. When the model calls a command tagged ai:confirm, fisk-ai pauses before running it and prompts the operator at the terminal, showing the resolved command line with its arguments, and offers three choices: run it once, run it and stop asking for that command for the rest of the session, or decline. Declining returns an authoritative result to the model (the command is not run and the model is told the decision is final), so it stops rather than working around the refusal. An “allow for the session” answer is remembered by command, regardless of its arguments: once you bless stream rm, every later stream rm call runs without asking again, so reserve that choice for a command you trust the agent to repeat. It applies for the rest of that run only; nothing is persisted across runs. The prompt is rendered on stderr (so a piped final answer stays clean), the displayed command line is stripped of terminal control sequences so model-supplied argument values cannot spoof what you see, and it denies by default: an interrupt, an end-of-input, or no interactive terminal declines rather than runs. Unlike human_in_the_loop, the tag is always active: there is no configuration flag to enable it.

The same gate can be extended to other tags with the harness.confirm_tags configuration key: any tag listed there gates its commands exactly as ai:confirm does, which lets an operator require confirmation for a tag the application already uses (for example impact:rw) without editing the application. It is additive to the always-on ai:confirm tag and matching is exact rather than a regex. A confirm_tags entry that matches no loaded command is reported as a warning at startup, since a typo would otherwise leave a command ungated. The approval prompt names the tag that gated the command, so you can tell why you are being asked. Run fisk-ai info to see each command’s tags and which commands a run would gate. Like ai:confirm, a confirm_tags tag gates both the agent loop and MCP, where it is requested through elicitation.

Any other tags are free-form: they have no built-in meaning to fisk-ai but can be matched by the tags field of an include or exclude rule.

All of a command’s tags, reserved and free-form alike, are also included in the tool description fisk-ai sends the model, as a trailing Tags: ... line, in both the agent and over MCP. This lets your prompt reference them, for example “always use ask_human_confirm before running any command tagged impact:rw”. The human-facing fisk-ai info listing keeps the plain description.

Memory

Memory gives the model a small key/value store that persists across runs, so it can keep durable notes (a layout it worked out, a convention, the outcome of an investigation) and pick them up next time rather than rediscovering them. It is opt-in and agent-mode only; like the human-in-the-loop tools it is never exposed over MCP.

harness:
  memory:
    enabled: true
    backend: file
    options:
      directory: memory

When enabled the model is offered four tools: memory_list (keys and their descriptions), memory_read (one memory by key), memory_write (save a memory with a key, a one-line description, and a body), and memory_delete. A key uses letters, digits and ., _, = or - (no slashes or spaces), which keeps it valid both as a filename and as a NATS KV key. memory_write creates by default and refuses to overwrite an existing key unless called with overwrite: true, so the model does not silently clobber a note; the create still fails cleanly if two writers race for the same new key.

At the start of a run the stored keys and descriptions are injected into the system prompt as an index so the model knows what it has saved; memory_list is the live view during the run. Turn the index off with no_index: true.

The file backend keeps each memory as a markdown file named for its key under the configured directory, which defaults to memory/<identity>. The identity is the agent’s name, set with the identity configuration field and defaulting to the application binary’s base name; the configuration reference covers it in detail. Point two agents at the same directory and they share a memory; leave the default and each agent keeps its own. Because the files are shared state, treat what a memory contains as data the model saved, not as trusted instructions.

We can use memory to ensure our agent never repeats jokes; change thesystem_prompt as follows:

harness:
  memory:
    enabled: true

system_prompt: |
  Tell short jokes using Cows!

  You have tools that can render a cow saying short sentences, when asked 
  use the tools to tell funny jokes.
  
  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. 
  If asked to tell non cow jokes, refuse and show no joke.

  Do not use emoji, keep general narration short, just stick to the jokes

  Save the jokes you told to a single memory file with all the past jokes 
  and make sure you dont repeat jokes you previously told.

  Finish your turn by making a funny quip related to the joke or cows or similar

We will get a new joke every time - be ready to get some awful jokes after a while :)

Safety

When Fisk AI runs a command in a CLI tool it passes a slice of arguments to the exec system call. No shell is involved that can be escaped or influenced.

App Builder is often involved and calls shell scripts, so App Builder commands need to be written defensively.

• Use type hints on arguments for ints, floats and so on
• Use is_shellsafe(value) on string input arguments
• Use escaping when passing arguments to commands, for example {{ .Arguments.message | escape }}
• Tag commands with the various helper tags so the harness understands the intent
• Mark every mandatory argument as required

Fisk AI has no tools that can interact with arbitrary files on the system. The only way it interacts with the system is through the supplied tools or the Memory feature.

Every command the agent runs gets the same protections:

• Its output combines stdout and stderr, preserving order, and is capped at 64 KiB so a chatty command cannot flood the model’s context
• The ANTHROPIC_API_KEY is stripped from its environment, so a tool can never read the agent’s own credentials
• LLMFORMAT=1 is set, signalling fisk applications to render output suited to an LLM rather than a terminal

Local LLMs

Local LLM hosting tools like ollama, LM Studio and others support exposing an Anthropic-compatible API. Fisk AI can communicate with those tools.

There are some caveats. To support a large number of tools, Fisk AI uses the Tool Search Tool, which these local runners do not support. When targeting a locally hosted model, the total tool count may need to stay around 15.

I set these environment variables before invoking fisk-ai to access my local Anthropic API instead of reaching to the internet.

$ export ANTHROPIC_BASE_URL=http://localhost:1234
$ export ANTHROPIC_API_KEY=lmstudio

MCP Servers

Instead of running an agent loop, Fisk AI can serve a Fisk application’s commands over the Model Context Protocol so another client, such as Claude Desktop or Claude Code, calls them directly as tools.

The tool set, the input schemas, and the tag rules are the same ones the agent uses. Only the caller changes: where the agent drives the tools with an LLM against a prompt, an MCP server hands the same tools to whatever client connects and lets it decide when to call them.

Starting a server

Serving over MCP needs less configuration than an agent: there is no agent loop, so system_prompt and llm.model are not used. A minimal config needs only the application to introspect, a tool selection, and the expose.agent.mcp block:

application_path: /usr/local/bin/nats
include:
  tools:
    - ^stream_
expose:
  agent:
    mcp: {}

Start the server with the mcp command:

$ fisk-ai mcp --config nats.yaml --port 8080

The transport is HTTP, the streamable MCP transport. The port is taken from --port (or FISK_AI_MCP_PORT); if unset, from expose.agent.mcp.port in the config; otherwise it defaults to 8080. All progress and logging go to stderr.

Use fisk-ai info to preview which tools a configuration exposes before starting the server:

$ fisk-ai info --config nats.yaml

Connecting a client

Wire an MCP client to the server by pointing it at the running URL. For Claude Code:

$ claude mcp add --transport http nats http://127.0.0.1:8080

A client that takes a JSON server map uses:

{
  "mcpServers": {
    "nats": {
      "type": "http",
      "url": "http://127.0.0.1:8080"
    }
  }
}

Configuration

MCP mode uses only the parts of the configuration that describe the application and the tool set. An identity becomes the MCP server name, defaulting to fisk-ai when unset; system_prompt, llm.model, and the agent-only harness settings are ignored.

Instructions

expose.agent.mcp.instructions sets a block of free text sent to clients when they connect. A client may pass it to the model as a hint about how to use the server, which suits orientation the individual tool descriptions are too terse to carry:

expose:
  agent:
    mcp:
      instructions: |
        These tools wrap the NATS CLI. Prefer stream_info before stream_edit,
        and treat all subjects as relative to the FOO account.

How tools are exposed

Each command becomes an MCP tool named by its command path, for example stream_info, with its input schema and a description built from the command’s help. Both the short help and any long help are surfaced to the client, so a command that carries detailed long help gives the model richer guidance than a one-line summary alone.

Each tool also carries MCP annotations:

• a readable title, the space-separated command path, so stream rm rather than the underscore tool name
• a read-only hint, derived from the command’s tags, when a command declares through a tagging convention that it only reads rather than mutates its environment, so a client can tell a safe query from a command that changes state; a command that declares no impact is left without the hint

The served tools are the agent’s include/exclude selection, narrowed further by expose.agent.tools when it is set. With neither, every command is served, subject to the tag rules below. Tool selection uses the same regular expressions over the tool name as the agent. A tool call runs the command and returns its result; a per-call timeout and a concurrency limit bound execution.

Command tags over MCP

The reserved command tags are honored over MCP, with two differences from the agent loop:

All of a command’s tags, reserved and free-form alike, are included in the tool description as a trailing Tags: ... line, the same as in the agent, so a client’s prompt can reference them.

Confirmation over MCP

Commands tagged ai:confirm, or a configured confirm_tags tag, require approval before they run. There is no local operator on the MCP path, so Fisk AI requests approval from the calling client through MCP elicitation: before running a gated command it asks the client to approve, showing the server name, the resolved command line, and the tag that gated it, and runs the command only on an explicit approval. A refusal, a dismissal, or any elicitation error denies the call and returns an authoritative result the model is told not to retry.

Not every client supports elicitation. expose.agent.mcp.confirm_over_mcp chooses what happens when the connected client cannot be asked:

expose:
  agent:
    mcp:
      confirm_over_mcp: always

A client that already has its own approval UI may prompt twice under auto or always; set never when the client’s own gating is trusted and the second prompt is unwanted.

What is not served

The built-in operator tools are agent-mode only and are never exposed over MCP, since there is no local operator on the MCP path:

• the human-in-the-loop ask_human_* tools
• the memory memory_* tools

Safety

Every served command gets the same per-command protections as the agent: it runs as an argument vector rather than through a shell, its arguments are bound to the command’s schema, its ANTHROPIC_API_KEY is stripped, its output combines stdout and stderr and is capped at 64 KiB, and LLMFORMAT=1 is set.

The threat model is wider than an agent run and worth understanding:

• Any client that can reach the server’s port can invoke every exposed tool with any schema-valid arguments. ai:deny and include/exclude are the gate on what is reachable, so scope the exposed set deliberately.
• There is no agent loop, prompt, or token budget bounding aggregate use. A per-call timeout and a concurrency limit bound execution, but not the total number of calls, so do not expose the server on an untrusted network.
• Command output is returned to the connected client rather than to Anthropic, so whoever connects sees whatever the commands print.
• Confirm-tagged commands are gated by elicitation, a request the client fulfills rather than an access control the server enforces. Use ai:deny, not confirmation, for anything that must never be reachable over MCP.

Knowledge (RAG)

Knowledge gives an agent a search tool over a locally built index of its own markdown and text documents. The agent gains a single in-process knowledge_search tool that returns the most relevant sections of the indexed corpus, each with a citation, so it can ground its answers in project documentation rather than its training data.

In AI terms this is a RAG (retrieval-augmented generation) system contained entirely in a single binary and a single process. It is aimed at keeping source data local and handles markdown files. It runs with or without a local embedding model; without one it uses full-text search alone.

Everything ships in the one fisk-ai binary. The index is a single SQLite file built and queried in-process, with no CGo and no external database. The orchestrating LLM stays remote at Anthropic or a local compatible model; only storage and retrieval are local. A local embeddings server is the only optional external process, and only when semantic search is turned on.

Enabling knowledge

The minimal enable needs no model and no server. Turn the feature on and point it at the documents to index:

harness:
  knowledge:
    enabled: true
    paths:
      - docs/

Build the index and search it from the command line, then run the agent, which now has the knowledge_search tool:

$ fisk-ai knowledge index docs/    # build the index, incremental, no embeddings needed
$ fisk-ai knowledge search "backpressure"
$ fisk-ai run "how does backpressure work?"

The index is incremental. A second knowledge index re-reads only files whose content changed, detected by hash, and reconciles deletions when a full configured root is walked.

Two retrieval tiers

Knowledge has two retrieval tiers. The lexical tier is always on and is the default; the vector tier is a separate opt-in.

The two tiers match a query in different ways. The lexical tier matches on words: a query and a section rank together when they share the same terms. The vector tier matches on meaning: a query and a section rank together when an embedding model places them close in vector space, even when they share no words. Lexical search is exact and literal; vector search is fuzzy and semantic. Hybrid mode runs both and fuses the results, so a query gets lexical precision on the terms it names and vector recall on the ideas it only paraphrases.

Lexical, the default

The lexical tier is an FTS5/BM25 full-text index. It is always active when knowledge is enabled and needs no embedding model, no external service, and no per-query cost. This is the baseline the feature works on for everyone, and for a corpus of local technical documents it is often all that is needed.

Lexical search is strongest when the query uses the corpus’s own vocabulary: an exact identifier, a command name, an error string, or a term of art the documents themselves use. Its limit is the mirror image. A query worded differently from the documents can miss a section that explains the same idea in other words, since a section that never uses the searched term does not match however relevant it is.

Semantic, opt-in

Add an embeddings block to turn on the vector tier. Its presence is the switch: with no block, knowledge stays lexical-only. When it is set, each chunk is embedded through a local OpenAI-compatible embeddings server, and a query is answered by fusing the lexical and vector rankings with Reciprocal Rank Fusion behind the one search call.

The benefit is recall on meaning rather than wording. A natural-language question finds the right section even when it shares no keywords with it: asking “how do I stop the agent spending too much” can surface the section on budgets though that section never says “spending”. This suits an agent, which phrases a search in its own words rather than the documents’ exact terms. Fusing the two tiers keeps lexical’s precision on named terms while adding this semantic reach, so the hybrid result is usually better than either tier alone.

The cost is what the vector tier adds. It needs a local embedding model and server to run, a --reindex to embed the existing corpus, and one embedding call per query at search time. Retrieval stays local either way; the vector tier trades the extra moving part for better recall on paraphrased and conceptual queries.

harness:
  knowledge:
    enabled: true
    paths:
      - docs/
    embeddings:
      base_url: http://127.0.0.1:1234/v1
      model: text-embedding-embeddinggemma-300m

The embedding model is user-chosen, so nothing about it is assumed. fisk-ai knowledge doctor probes the configured server and reports the model, its vector dimension, and whether its output is normalized. After turning embeddings on, rebuild the index so the vectors are populated:

$ fisk-ai knowledge doctor
$ fisk-ai knowledge index --reindex
$ fisk-ai knowledge stats

Changing the model, its dimension, or a prefix changes the vector identity and forces a --reindex. The index refuses a mismatched model upfront, before embedding anything, rather than silently returning wrong rankings.

Tier line

Every surface, the CLI commands and the knowledge_search tool result, prints one canonical tier line so it is never ambiguous which tier answered a query:

tier: lexical (FTS5) - no embeddings configured
tier: hybrid (FTS5 + vectors, RRF) - model=<name> dim=<n>
tier: hybrid -> DEGRADED to lexical (embeddings unreachable: <reason>)

A configured embeddings server that is unreachable at query time degrades to lexical-only and says so, rather than failing the search. A configured embeddings server that is unreachable at index time fails loud, so an index the user asked to be semantic is never silently built lexical-only.

When to enable embeddings

Start lexical. It has nothing to run and no per-query cost, and it is often enough on its own. Add embeddings when the searches that matter are worded differently from the documents.

The two are not exclusive: enabling embeddings keeps the lexical tier and fuses the two, so nothing is lost by turning it on beyond the extra model to run.

Configuration

The harness.knowledge block mirrors harness.memory. An absent block, or enabled: false, means off.

harness:
  knowledge:
    enabled: true
    paths:
      - docs/
    directory: ""
    top_k: 5
    max_injected_tokens: 6000
    embeddings:
      base_url: http://127.0.0.1:1234/v1
      model: text-embedding-embeddinggemma-300m
      api_key_env: RAG_EMBED_KEY
      timeout: 30s
      query_prefix: ""
      document_prefix: ""

The directory follows the same rule as memory’s options.directory: resolved against the working directory when it is not absolute, and defaulting to knowledge/<identity>. The identity is the agent’s name, so two agents pointed at the same directory share an index and the default keeps each agent’s index its own.

Embeddings

The embeddings block is only read when the vector tier is on. It describes a local OpenAI-compatible endpoint that fisk-ai POSTs to at <base_url>/embeddings.

api_key_env names an environment variable rather than carrying the secret, so no secret lives in agent.yaml and none is logged. Prefixes default to empty because the model is user-chosen and a wrong prefix is worse than none; the models that need one document it. Run knowledge doctor to see whether a chosen model expects a prefix.

The knowledge_search tool

When knowledge is enabled the agent is offered one tool, knowledge_search, that takes a query and an optional top_k. It runs the lexical search, adds and fuses the vector search when the vector tier is on, and returns the ranked sections. The effective count is min(requested or configured top_k, 20), and the total returned text is capped at max_injected_tokens.

Each result carries a citation token of the form <relpath>#<ordinal>, the file path relative to the index root and the chunk’s position in that file, alongside the human-readable heading path of the section. The same token is printed by knowledge search and knowledge sources and accepted verbatim by knowledge show, so a result can be resolved back to its full text.

Results are returned to the model as untrusted reference data, framed as material to draw on rather than as instructions. When the store has no index yet the tool returns a soft index_not_built status naming the fix, rather than failing the run, so a missing index never bricks agent startup.

CLI commands

The fisk-ai knowledge command builds and inspects the index. It is separate from the agent’s knowledge_search tool; the CLI never runs the agent. Every command reads --config (default agent.yaml) and prints the tier line.

The command is also available as fisk-ai rag.

knowledge index is incremental and per-file: a file whose hash is unchanged is skipped, a changed file is re-chunked, and a walk of a full configured root reconciles deletions. --dry-run lists the files and an embedding-call estimate without embedding anything, and --reindex forces a full rebuild. Indexing walks markdown and text files only, by the .md, .markdown, .txt, and .text extensions, and always excludes the store directory itself and the memory/ directory.

knowledge doctor degrades for lexical-only users and never exits non-zero solely because embeddings are absent. It always checks that the store is present and writable, that FTS5 is compiled in, and that the configured paths resolve. Only when embeddings is configured does it probe the endpoint and check the stored model and dimension for a mismatch.

knowledge reset without --force refuses and names the document and chunk count it would delete; knowledge reset --force clears every row and leaves a clean empty index in place, ready for the next knowledge index.

Store location and layout

The index is project-local. It lives at knowledge/<identity> relative to the working directory, alongside the memory/<identity> store, which suits the one-project-per-directory workflow where an agent.yaml, a memory/ directory, and a knowledge/ directory sit side by side. The directory field overrides the location.

The store is a single SQLite file with its -wal and -shm sidecars. The agent opens it read-only while knowledge index is the single writer, so an index can be rebuilt while an agent runs without the agent seeing a half-written state. A cross-process lock stops two indexers from running at once.

Serving over MCP

knowledge_search is the one built-in tool that can also be served over MCP. It is read-only and needs no operator prompt, unlike the human-in-the-loop and memory tools, which stay agent-only. Exposure is off by default and enabled through an explicit allowlist:

expose:
  agent:
    mcp:
      port: 8080
      builtins:
        - knowledge_search

Only knowledge_search is accepted in builtins; listing any other built-in is a configuration error that names the exposable set. The MCP process opens the read-only store and, when embeddings are configured, embeds the query itself, so the embeddings server must be reachable from that process. Degrade-to-lexical and the stored model validation apply unchanged.

Security

The index holds the verbatim text of every indexed document, unencrypted on disk. modernc.org/sqlite has no pure-Go at-rest encryption, so the posture matches the memory feature: the file and its sidecars are created 0600 inside a 0700 directory.

• The 0600 permission protects the file from other users on the same host. It does not protect against disk theft, backups, or a stolen copy, so do not index secrets.
• Retrieved chunks are framed as untrusted reference data and stripped of terminal control sequences before any TUI render, so indexed text cannot spoof the display or inject instructions.
• Embeddings secrets are supplied by environment-variable name and never logged. A non-loopback embeddings base_url must use https, and the request timeout is enforced.
• Over MCP the allowlist is the only gate, and only the read-only knowledge_search is ever served; no index or write path is reachable over MCP.

Reference

A Fisk AI agent is described by a single YAML configuration file. It names the application to drive, selects which of its commands become tools, and sets the model, the prompt, and how the harness behaves. The run, mcp, and a2a commands all read the same file; each uses the parts it needs and ignores the rest.

The --config flag selects the file, defaulting to agent.yaml in the working directory:

$ fisk-ai run --config nats.yaml "report on the ORDERS stream"

Each section below is a slice of that file: read it top to bottom and you have seen every setting Fisk AI understands. Fields that are required are called out as such; everything else has a working default and can be left out.

A minimal file

The smallest useful agent names the application, sets a model, and gives a prompt:

# agent.yaml - drive the NATS CLI as an agent

application_path: /usr/local/bin/nats

llm:
  model: claude-sonnet-4-6
  budget:
    max_tokens: 200000
    max_iterations: 50
    call_timeout: 120s

system_prompt: |
  You manage NATS JetStream Streams using tools.

Everything after this point expands on those blocks and adds the optional ones.

A knowledge-only agent

application_path is optional. Leave it out to run an agent with no wrapped application, on the built-in tools alone. This is useful for a knowledge agent that answers from an indexed corpus over knowledge:

# agent.yaml - answer questions from a local knowledge base, no wrapped app

llm:
  model: claude-sonnet-4-6

system_prompt: |
  You answer questions using the knowledge_search tool over the indexed docs.

harness:
  knowledge:
    enabled: true

With no application_path, the identity defaults to fisk-ai; set an explicit identity to keep the knowledge/<identity> and memory/<identity> stores separate when you run more than one such agent in a directory.

Identity and application

# The name of the agent. Used in discovery and reused as a NATS queue
# group, so it must contain only letters, digits, "-" or "_". If you
# leave it out it defaults to the application binary's base name, or to
# "fisk-ai" when no application_path is set; set it explicitly when the
# derived name carries a dot, a space, or other characters, which are
# rejected, or to keep memory/knowledge stores separate between agents.
identity: nats

# Path to the Fisk application binary to introspect and run. OPTIONAL.
# When set, the binary is introspected once at startup to obtain its
# command tree and per-command JSON schemas. Leave it out to run an agent
# on the built-in tools (knowledge, memory, human_in_the_loop) and any
# remote tools alone, with no wrapped application. Required only for "a2a"
# mode, which serves the wrapped application's tools.
application_path: /usr/local/bin/nats

# The system prompt describing what the agent should do. REQUIRED for a
# "run", ignored by "mcp" and "a2a" mode. Think of it as a one-file SKILL:
# describe the goals and give broad guidance.
system_prompt: |
  You manage NATS JetStream Streams using tools.

identity is load-bearing beyond a label: it is the NATS subject key when the agent serves or is discovered over agent-to-agent, and the default memory directory is memory/<identity>. Keep it to the safe character set so those uses stay valid.

application_path is optional for run and mcp modes and required only for a2a, which serves the wrapped application’s tools and cannot serve the built-ins. When set, the target must be built with a current Fisk (v0.9.0 or newer) that supports --fisk-introspect and precomputed per-command schemas. When it is left out, Fisk AI skips introspection entirely and the agent runs on its built-in and remote tools alone; see a knowledge-only agent below.

Tool selection

include and exclude choose which of the application’s commands become tools. Each takes a list of regular expressions matched against the tool name, and a list of fisk tags:

# Keep only the commands whose tool name or tag matches. When "include" is
# present, a command must match it to be exposed.
include:
  # Regular expressions matched against the tool name: the command path
  # joined with underscores, so the "stream info" command is "stream_info".
  tools:
    - ^stream_
    - ^consumer_info$
  # Match commands by fisk tag. An empty string "" matches untagged
  # commands. The reserved ai:deny tag is always active and can never be
  # included back in.
  tags:
    - scope:read

# Remove matching commands. Applied as a filter: a command that matches
# "exclude" is dropped even if "include" allowed it.
exclude:
  tools:
    - ^stream_rm$
  tags:
    - scope:system

A tool’s name is its command path joined with underscores, so a nested command like stream info becomes stream_info. Grouping commands and hidden commands are skipped and never become tools. include and exclude can be used together: for example include ^stream_ but exclude ^stream_rm$. Commands tagged ai:deny are dropped before any of this runs and can never be added back.

Run fisk-ai info to preview the resulting tool set before a run.

Model and run budget

The llm block selects the model and bounds a single run. llm.model is the only required field in it:

llm:
  # The model identifier. REQUIRED. Accepts any value the Anthropic API
  # accepts; the well-known identifiers are listed under "Models" below.
  model: claude-sonnet-4-6

  # Bounds on a single run so the agent loop cannot spend without limit.
  # The run stops with a summary once any of these is reached, whether or
  # not the task is complete.
  budget:
    # Cumulative token spend cap for the run. Default 200000.
    max_tokens: 200000
    # Maximum agent loop iterations. Default 50.
    max_iterations: 50
    # Per-call timeout as a Go duration string, for example "60s" or
    # "2m". Default "120s".
    call_timeout: 120s

  # Controls whether the model exposes its reasoning. Off by default; when
  # off, no thinking is requested and the model uses its default behavior.
  thinking:
    # When true, asks the model to think and surfaces its reasoning
    # separately from the answer (thought-bubble lines on stderr in shell
    # mode, folding blocks in the TUI). Older models that predate adaptive
    # thinking (Sonnet 4.5, Haiku 4.5) reject it, so leave it off for those.
    enabled: false

  # When true, disables Anthropic prompt caching for the run. Left off,
  # Fisk AI caches the stable prefix of each request to lower cost and
  # latency on multi-turn runs.
  no_prompt_cache: false

Larger models reason better on complex, long-horizon tasks; smaller models like Haiku are faster and cheaper for narrow ones. When the agent exposes ten or more tools it relies on the model’s server-side tool search, which recent models support and older ones do not; see Models.

Harness

The harness block governs how the agent harness behaves during a run, as distinct from the model (llm) or the tool selection. Everything in it is optional and the whole block can be omitted to leave every setting at its default. These settings apply to the agent loop only; mcp and a2a mode ignore them.

harness:
  # Opt-in built-in tools that let the model ask the operator a question
  # at the terminal (agent mode only).
  human_in_the_loop:
    # When true, offers the model the ask_human_confirm, ask_human_select,
    # and ask_human_input tools. Off by default.
    enabled: true

  # Command tags that, in addition to the always-on ai:confirm tag, gate a
  # command behind operator approval before it runs. Matching is exact, not
  # a regex, and additive to ai:confirm. An entry that matches no loaded
  # command is reported as a warning at startup.
  confirm_tags:
    - impact:rw

  # A hard off switch for the full-screen terminal UI: the agent always
  # uses line-by-line output, even on an interactive terminal, and the
  # command line cannot turn the UI back on. Use the --no-tui flag for a
  # one-off run instead. Negative switch, no effect in the line UI.
  no_tui: false

  # The full-screen UI rings the terminal bell each time a run blocks
  # waiting on you (an approval gate or an ask_human_* prompt). On by
  # default; set true to silence it. Negative switch, no effect in the
  # line UI.
  no_bell: false

  # Opt-in built-in key/value store that survives across runs (agent mode
  # only).
  memory:
    # When true, offers the model the memory_list, memory_read,
    # memory_write, and memory_delete tools. Off by default.
    enabled: true
    # The store implementation. Defaults to "file", which keeps each
    # memory in a markdown file under a directory; it is the only backend
    # today.
    backend: file
    # By default the stored keys and descriptions are injected into the
    # system prompt at run start so the model knows what it has saved. Set
    # true to keep the store's contents out of the prompt. Negative switch.
    no_index: false
    # Backend-specific settings. For the "file" backend: "directory", the
    # path memory files live under, defaulting to "memory/<identity>".
    options:
      directory: memory

human_in_the_loop lets the model decide when to ask; the ai:confirm tag and confirm_tags gate a command the model wanted to run anyway. The two are compared in detail under Command tags and in the Agents guide.

Point two agents at the same memory directory and they share a memory; leave the default and each keeps its own. Treat what a memory contains as data the model saved, not as trusted instructions.

Command tags

Fisk commands can carry tags, set in their fisk definition or, for App Builder applications, in YAML. Any tag can be matched by include/exclude, and three are reserved and interpreted by Fisk AI itself:

ai:confirm denies by default: an interrupt, an end-of-input, or no interactive terminal declines rather than runs. An “allow for the session” answer is remembered by command regardless of its arguments, for the rest of that run only. harness.confirm_tags extends the same gate to any other tag your application already uses. Over MCP these gates are requested through elicitation instead of a local operator prompt; over agent-to-agent, confirmation-gated commands are not served at all. The full behavior is documented under Command Tags in the Agents guide.

All of a command’s tags, reserved and free-form alike, are appended to the tool description Fisk AI sends the model as a trailing Tags: ... line, so a prompt can reference them.

Serving over MCP

To serve the same tools over the Model Context Protocol instead of running the agent loop, add an expose.agent.mcp block. It is opt-in: without this block, fisk-ai mcp refuses to start. MCP mode uses only the fields that describe the application and the tool set; system_prompt, llm.model, and the harness settings are ignored.

expose:
  agent:
    # The opt-in block that enables MCP serving. Must be present, even if
    # empty ({}), for "fisk-ai mcp" to start.
    mcp:
      # Default listen port, used when neither --port nor the
      # FISK_AI_MCP_PORT environment variable is set. Default 8080.
      port: 8080

      # Free-text guidance sent to clients when they connect. A client may
      # pass it to the model as a hint about how to use the server, a good
      # place for orientation the terse per-tool descriptions cannot carry.
      instructions: |
        These tools wrap the NATS CLI. Prefer stream_info before
        stream_edit, and treat all subjects as relative to the FOO account.

      # How confirmation-gated commands (ai:confirm or a confirm_tags tag)
      # behave when the connected client cannot be asked through
      # elicitation:
      #   auto   - default; ask clients that can elicit, run ungated for
      #            clients that cannot
      #   always - ask clients that can elicit, refuse for clients that
      #            cannot be asked
      #   never  - never ask, run gated commands ungated, delegating
      #            approval to the client's own UI
      confirm_over_mcp: auto

    # Optional: narrow the served set further, within the top-level
    # include/exclude selection. With neither, every selected command is
    # served (subject to the tag rules). Same regex-over-tool-name and tag
    # matching as the top-level filters.
    tools:
      include:
        tools:
          - ^stream_
      exclude:
        tools:
          - ^stream_rm$

The served tools are the agent’s top-level include/exclude selection, narrowed further by expose.agent.tools when set. identity, if set, becomes the MCP server name. Elicitation is a request the client fulfills, not an enforcement boundary; for a command that must never be reachable over MCP, use ai:deny rather than confirmation. The MCP Servers guide covers this mode end to end.

Agent-to-agent

Fisk AI agents can also serve tools to, and import tools from, one another over NATS with no LLM on the serving side. Both sides use a named NATS context, given as nats_context.

# Name of a NATS context (as managed by "nats context" and resolved by
# jsm.go) used to connect to NATS. REQUIRED when remote_tools is set or
# when running "fisk-ai a2a".
nats_context: ngs

expose:
  agent:
    # When true, "fisk-ai a2a" serves this agent's tools over NATS. Opt-in:
    # without it, "fisk-ai a2a" refuses to start. Like MCP mode, serving
    # needs only application_path, identity, nats_context, and the tool
    # selection. Confirmation-gated commands are never served, since there
    # is no operator to approve them.
    agent_to_agent: true

# Import tools from one or more remote fisk-ai agents over NATS and expose
# them to this agent alongside its local tools.
remote_tools:
  - # The remote agent's identity (also the NATS subject key). REQUIRED.
    name: nats
    # A prefix for the imported tool names. Applied only when a bare name
    # would clash with a local tool or another remote's tool. Defaults to
    # "name".
    alias: nats
    # Select which of the remote agent's tools to import, matched against
    # the tool name only. A "tags" filter cannot be honored, since
    # discovery does not carry tags, and an exclude-by-tag is rejected at
    # startup.
    include:
      tools:
        - ^stream_
    exclude:
      tools:
        - ^stream_rm$

Imported tools keep their own name where it is unambiguous, and take the <alias>_<name> form only when the bare name would collide. A run is strict: an unreachable or unimportable remote agent fails the run. fisk-ai info is lenient and reports each remote host’s reachability instead.

Models

Well-known Anthropic model identifiers are available as constants in the config package; any value the Anthropic API accepts may be used in llm.model, local LLMs will have their own convention. fisk-ai does not restrict what you enter here.

Every model in the table supports the server-side tool-search tool that deferred tool discovery relies on. Anthropic’s tool search is generally available on Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later; Claude Opus 4.1 and earlier, and local models, do not support it. If you point llm.model at an older identifier or a local model while exposing ten or more tools, the model is left holding only the tool-search tool with no way to reach the deferred commands and the run stalls. With such a model, keep the exposed set below ten tools (around 15 for local runners) so every tool is sent directly.

Command-line flags and environment

Some behavior is set per run on the command line rather than in the file. The flags override the file where they overlap, except for the hard off switches (harness.no_tui), which the command line cannot re-enable.

The MCP server port also reads FISK_AI_MCP_PORT, which --port overrides and which in turn overrides expose.agent.mcp.port. Sessions, chat, and their durability semantics are covered in the Agents guide.

Safety

The configuration is the boundary on what the model can reach: application_path fixes the one binary it can drive (and with no application_path set the agent can drive no external binary at all), include/exclude and ai:deny fix which of its commands become tools, and nothing outside that set is callable. Commands run as an argument vector rather than through a shell, their arguments are bound to each command’s schema, the ANTHROPIC_API_KEY is stripped from their environment, output is capped at 64 KiB, and LLMFORMAT=1 is set. The Agents and MCP guides describe the full threat model for each mode.

Design

Design and internals documentation for Fisk AI. It complements the user-facing guides by explaining how the code is put together and why.

Start with the Code Map for a guided deep-dive: what the project is, how the packages layer, and how each subsystem works.

• Code Map: A guided deep-dive into the Fisk AI codebase: architecture, subsystems, and the flows that connect them.
• Development Roadmap: planned direction for the Fisk AI platform