Connecting a workstation | AI Council docs

What you need

Claude Code on the developer's machine.
Network access to the Council server at the same address as the web UI. No internet access needed: packages are downloaded from the server.
A project that has been added and analyzed: delivery works on analyzed entities.

Installation

Account menu → Profile & API Keys → + Create Key.
Copy the command from the Install hooks on your machine block. The address and key are already filled in. The full key is shown once; afterwards the list shows only its prefix.
Run the command on your machine.
Open Claude Code in the project directory and start a new session.

AI_COUNCIL_API_TOKEN=aic_xxx AI_COUNCIL_URL=https://<address> \
  bash -c "$(curl -fsSL https://<address>/install-hooks.sh)"

The command unpacks the hooks into ~/.claude/hooks/, writes the address and token to ~/.claude/settings.json, and registers the hooks and the Council MCP server. Running it again creates no duplicates. Hooks update themselves at the start of a new session after a server update.

Keys are personal

Hooks call the server on behalf of the key owner, and access is isolated per user. Don't share one key across the team.

What happens during a session

Hooks and MCP are separate channels. Hooks add context on their own at the moments listed below. MCP tools are called by the agent when it decides to.

Moment	What the hooks do
Session start	Pull hook updates and, if the session was opened for a task, add the task note
Every prompt	Add project conventions in portions: over several prompts the agent receives the full rulebook
First code read	Reject it until at least one knowledge base tool has been called in the session, and suggest what to call
Reading and editing a file	Add the conventions and knowledge entries bound to that file, within the configured limits
File edits	Notify the server about the change so analysis re-reads what changed
End of turn	Once per session, show a checklist if the working tree has uncommitted changes
Knowledge write	Bind what was written to the files the agent worked with

Moment

What the hooks do

Session start

Pull hook updates and, if the session was opened for a task, add the task note

Every prompt

Add project conventions in portions: over several prompts the agent receives the full rulebook

First code read

Reject it until at least one knowledge base tool has been called in the session, and suggest what to call

Reading and editing a file

Add the conventions and knowledge entries bound to that file, within the configured limits

File edits

Notify the server about the change so analysis re-reads what changed

End of turn

Once per session, show a checklist if the working tree has uncommitted changes

Knowledge write

Bind what was written to the files the agent worked with

Drafts

The Draft mode toggle on the Profile & API Keys screen: your knowledge entries and conventions are saved as drafts and visible only to you until confirmed. Task agents have no drafts: their entries are saved on the task branch and carried over to the default branch on merge.

Context delivery volume

Profile & API Keys → Context delivery. Limits are set in characters for your account and count only the channels below. Anything the agent requested through tools is not counted. Each channel has three settings: No limit, Limit and Off.

Channel	What arrives
Rules with every prompt	Project conventions before each prompt, in rotation
Rulebook at the start	The full rulebook once, before the agent's first action
Rules for a file	Conventions for the file the agent reads or edits
Knowledge for a file	Knowledge entries about that file
Whole session	Overall limit per conversation
Knowledge already sent	How long an entry that was already sent is not resent in full

Channel

What arrives

Rules with every prompt

Project conventions before each prompt, in rotation

Rulebook at the start

The full rulebook once, before the agent's first action

Rules for a file

Conventions for the file the agent reads or edits

Knowledge for a file

Knowledge entries about that file

Whole session

Overall limit per conversation

Knowledge already sent

How long an entry that was already sent is not resent in full

Troubleshooting

Symptom	Cause and fix
Knowledge and conventions don't arrive	The project hasn't been analyzed, or the file is outside the analyzed entities
mcp__ai-council__* tools don't respond	Check AI_COUNCIL_URL and the token in ~/.claude/settings.json, and that the address is reachable
The agent runs short of context for its work	Lower Rules with every prompt and Knowledge for a file, or switch them to Limit
The same knowledge arrives repeatedly	Increase the Knowledge already sent window
Failed to connect … port 443	The installation runs without TLS: replace https with http in the command, or set up TLS
Key is compromised	Revoke the key in the list or click Regenerate

Symptom

Cause and fix

Knowledge and conventions don't arrive

The project hasn't been analyzed, or the file is outside the analyzed entities

mcp__ai-council__* tools don't respond

Check AI_COUNCIL_URL and the token in ~/.claude/settings.json, and that the address is reachable

The agent runs short of context for its work

Lower Rules with every prompt and Knowledge for a file, or switch them to Limit

The same knowledge arrives repeatedly

Increase the Knowledge already sent window

Failed to connect … port 443

The installation runs without TLS: replace https with http in the command, or set up TLS

Key is compromised

Revoke the key in the list or click Regenerate