Connect an AI agent

Agent access lets an AI agent on your computer work with Kioku. It can search and read your material, import web pages, quote extracts from them, and make cards. It’s off until you turn it on. Each agent asks you before it connects, and you choose which Collections it can reach and what it may do there. An agent can change or move to the Trash only what it added itself, never your own material.

Where your content goes

An agent usually sends what it reads to the company that runs its AI model, under that company’s terms. Give an agent only the Collections you’re comfortable sharing with it. See the Privacy Policy.

Before you begin

• Agent access is in Kioku for macOS. It isn’t in the Windows and Linux builds yet.
• Kioku must be open while an agent uses it. Agents work through the running app, in the Collection that’s open.
• Keep Kioku in your Applications folder. The setup below names Kioku’s location, so moving Kioku afterwards means setting each agent up again.

Turn on agent access

1. Open Settings.
2. Go to Privacy.
3. Under Agent access, turn on Allow agent access.

Turning it off disconnects every agent at once. Their pairings are kept for when you turn it on again.

Connect an agent app

Under Connect an agent, choose your agent app. Each tab shows the lines to add, with this Kioku’s own location in them. Select Copy to copy them.

Claude Code

Paste the copied line into a terminal and run it once. It adds Kioku to Claude Code for all your projects. In a new session, ask Claude Code to do something in Kioku.

Codex

Add the copied lines to ~/.codex/config.toml. They let Kioku’s tools run without Codex asking each time. Without that, Codex refuses them when it can’t ask, as in codex exec. The lines also give a call up to two minutes, which a large import can need.

Claude Desktop

In Claude Desktop, open Settings, then Developer, then Edit Config. Add the copied lines inside the outer braces of claude_desktop_config.json, then restart Claude Desktop.

If the file already has "mcpServers", add only the "kioku": { … } entry inside it, separated from the entry before it by a comma. Two "mcpServers" in one file make Claude Desktop reject the file.

An agent that works in a terminal

Some agents work by running commands. They use Kioku’s kioku command.

1. Choose Shell, then select Add to PATH. This links ~/.local/bin/kioku to Kioku’s command, and needs no administrator rights.
2. Tell your agent to run kioku pair --name "…" once, with a name you’ll recognize. Kioku asks you to allow it, as below.
3. Then kioku help lists every command it can use.

If a terminal says command not found: kioku, add ~/.local/bin to your PATH. For zsh, the default on macOS, run this once and open a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Allow an agent

The first time an agent app uses Kioku, or an agent in a terminal runs kioku pair, Kioku asks you about it:

1. A dialog shows the agent’s name, such as Claude Code, and a code. If the agent shows you a code too, check that the two match.
2. Choose the Collections it may use, and what it may do there: Read, Add material, Edit what it added, and Move what it added to the Trash.
3. Select Allow.

An agent app such as Claude Code waits for your answer, then carries on with what it was asked. Kioku’s dialog stays open for two minutes:

• If the agent stops waiting first, it says Kioku is asking you. Allow it in the dialog, then ask the agent again.
• If the dialog closed before you answered, ask the agent again, and it asks again.

Select Deny if you didn’t expect the request. Kioku then waits a while before it shows another request from any program, and longer after each one you don’t allow. Opening Settings → Privacy → Agent access ends that wait, for an agent you do mean to allow. Select Deny and turn off agent access to stop all requests until you turn agent access back on.

What an agent can and can’t do

With the access you allow, an agent can:

• search the open Collection, list its topics and cards, and read a topic’s text;
• make topics, and import a web page as a topic;
• quote an extract from a topic, which Kioku checks against the topic’s text and highlights there;
• make basic and cloze cards;
• edit, retitle, move and tag what it made, and move it to the Trash and back.

It can’t:

• change, move or trash your own material;
• delete anything for good: the Trash is as far as it goes;
• review cards, or change your settings.

When you edit something an agent made, it becomes yours, and the agent can no longer change it. If an agent changes something while you’re editing it, the editor shows a bar. Choose Keep mine to keep your typing, or Use the new version to take the agent’s.

Change or revoke access

Each agent you allowed is listed under Paired programs, with when it paired and when it was last used.

• Edit what an agent may do, or which Collections it can reach.
• Revoke an agent to turn it away. It’s listed until you remove it.
• Remove an agent to forget it. It has to ask again to connect.

Troubleshooting

• “Kioku is not running, or agent access is off.” Open Kioku and check that Allow agent access is on.
• Claude Desktop doesn’t show Kioku’s tools. Check that claude_desktop_config.json has one "mcpServers", with "kioku" inside it, then restart Claude Desktop.
• The agent is refused a Collection. It can reach only the Collections you chose, and only the one that’s open. Open the Collection, or edit the agent’s access under Paired programs.
• You moved Kioku. Copy the lines again from Connect an agent, and select Add to PATH again.
• Codex says a tool call needs approval. Check that default_tools_approval_mode = "approve" is in Kioku’s table in ~/.codex/config.toml.