🔌 Claude Code plugin & hooks

The plugin connects Claude Code to the Codelux AI daemon on your machine: the MCP server with the 8 tools, three slash commands, and five hooks that make memory and the file lock happen without the model having to remember to call anything.

Install

Or inside Claude Code: <code>/plugin marketplace add codeluxai/codelux</code>, then <code>/plugin install codelux@codelux</code>. The hooks need <code>bash</code> and <code>curl</code> (on Windows, Git Bash). If the daemon is not running every hook is silent — Claude Code works as if the plugin were not there.

The five hooks

The AGENTS.md / CLAUDE.md block

At every session start and every <code>memory_set</code>, Codelux AI rewrites the block between <code>&lt;!-- codelux:start --&gt;</code> and <code>&lt;!-- codelux:end --&gt;</code> in <code>&lt;project&gt;/AGENTS.md</code> (created if missing) and, when the file exists, in <code>&lt;project&gt;/CLAUDE.md</code>: status, next step, traps and recent decisions, at most 60 lines. Text outside the markers is never touched. Agents that read no hooks still read this file.

Slash commands

Codex and Gemini CLI (experimental)

The same scripts run from any agent that supports command hooks. The plugin folder ships two ready-made files: <code>hooks/codex.hooks.json</code> for Codex (copy to <code>&lt;repo&gt;/.codex/hooks.json</code>) and <code>hooks/gemini.settings.json</code> for Gemini CLI (merge its <code>hooks</code> object into <code>&lt;repo&gt;/.gemini/settings.json</code>). The MCP server is the same URL for every agent. What the hooks do not carry, the <code>AGENTS.md</code> block does.

🤖 Set up your AI agent

Codelux AI reaches every agent through two channels: the MCP server (the tools) and the hooks (what happens without the model having to ask). Below is the complete, copyable configuration for each provider.

What the hooks give you

The whole procedure, step by step

<b>The providers' apps must have the Codelux AI hooks active: the main session and its subagents send everything.</b> With the hooks on every tool (PreToolUse + PostToolUse + PostToolUseFailure for Claude Code, PreToolUse/PostToolUse for Codex, BeforeTool/AfterTool for Gemini CLI) Codelux AI records one row per tool call, native or Codelux AI, for the session and for each subagent, under the agent's name.

What a row holds: provider, session or subagent, tool, the essential arguments (Read: file and lines; Grep/Glob: pattern, path, glob; Edit/Write: file and lines or bytes touched; Bash: the command cut to 200 characters; Agent: type and description; MCP: tool and key arguments), the size of the response in bytes and lines, the duration and the outcome. Never a file's content, an output or the text of an edit; keys, tokens and passwords in commands and arguments become <code>[redacted]</code>. Everything stays on your machine (the project's local store, 30 days): nothing is sent to the server, nothing goes into the Team's events.

The app's <b>Procedure</b> view (per project, per agent, per day) shows the sequence with times, the files read again although unchanged, the big files read whole when one symbol was enough, the share of Codelux AI calls, the tokens estimated per read and the rounds that could be saved, with the concrete alternative (<code>code_context X</code> instead of 2,000 lines). Export it as Markdown, or read it with <code>GET /api/project/{id}/procedure?from=&amp;to=&amp;who=&amp;format=md</code> or <code>codelux procedure &lt;projectid&gt;</code>.

Hints to the running agent: only when the saving is clear, one sober line in its context ("you already read X at 10:59 (lines 1-200) and it has not changed since", "X is an indexed symbol: code_context X"), at most 2 a turn, never blocking. They can be turned off per project in the Procedure view.

Reading only what is needed: <code>GET /api/project/{id}/read?file=&amp;from=&amp;to=</code> (REST), <code>codelux read &lt;projectid&gt; &lt;file&gt; &lt;from&gt; &lt;to&gt;</code> (CLI) and, on MCP, <code>code_context</code> with <code>name="&lt;file&gt;:&lt;from&gt;-&lt;to&gt;"</code> answer the lines asked (at most 400), numbered, with the file's total, the estimated tokens and the next range; <code>code_context name="&lt;file&gt;"</code> answers the file's outline (symbols with their lines). Every Codelux AI read is in the same Procedure.

At a glance

Before you start

• Codelux AI is running and the project is added in the app. The MCP address is <code>http://localhost:8766/mcp</code>; if Codelux AI runs on another port, use yours.
• The hooks need <code>bash</code> and <code>curl</code>; on Windows, Git Bash.
• Codex and Gemini CLI: get the plugin folder from <a href="https://github.com/codeluxai/codelux" rel="noopener" target="_blank">github.com/codeluxai/codelux</a> and, in the files below, replace <code>CODELUX_PLUGIN</code> with the full path of the folder that holds <code>scripts/</code>. On another port, start the agent with the variable <code>CODELUX_PORT</code> set.

The AGENTS.md block

Every agent reads the same block between <code>&lt;!-- codelux:start --&gt;</code> and <code>&lt;!-- codelux:end --&gt;</code>: a few fixed lines saying which Codelux AI tools to use and that the memory arrives by itself or with <code>memory_get</code>. It carries no date and no status, so it is identical in every session and does not invalidate the provider's prompt cache. The session-start hook keeps it up to date; without hooks, run this once from the project folder:

It creates <code>AGENTS.md</code> with the block when missing (and <code>CLAUDE.md</code> with the single line <code>@AGENTS.md</code>); text outside the markers is never touched. If the folder is not a project registered in Codelux AI, nothing is written.

Claude Code

Full support. The plugin brings everything: the MCP server, the hooks and the slash commands. There is nothing to copy by hand.

1. Install the plugin:
   claude plugin marketplace add codeluxai/codelux claude plugin install codelux@codelux
   or, inside Claude Code, <code>/plugin marketplace add codeluxai/codelux</code> and then <code>/plugin install codelux@codelux</code>. On another port: <code>claude plugin install codelux@codelux --config port=&lt;port&gt;</code>, then restart Claude Code.
2. Restart Claude Code in the project folder and type <code>/codelux:status</code> to check that it is connected.
3. Instruction file: at session start the plugin writes the block in <code>AGENTS.md</code> and, if <code>CLAUDE.md</code> does not exist, creates it with one line that imports it. An existing <code>CLAUDE.md</code> that does not import <code>AGENTS.md</code> gets the block appended.
   @AGENTS.md
4. Hooks: the file is <code>hooks/hooks.json</code> inside the plugin, already wired. This is the part that takes and releases the lock (the other hooks are in <a href="#" data-doc-go="hooks">Claude Code plugin &amp; hooks</a>):
   "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" acquire", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" release", "timeout": 10 } ] } ], "PostToolUseFailure": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" release-failed", "timeout": 10 } ] } ]
   And the part that sends the procedure (every tool, matcher <code>.*</code>):
   "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" pre", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" post", "timeout": 5 } ] } ], "PostToolUseFailure": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" post-fail", "timeout": 5 } ] } ]
5. MCP: the plugin registers the server <code>codelux</code>. Without the plugin, see <a href="#" data-doc-go="ide">IDE Setup (MCP)</a>.

Codex

Experimental. The hooks format comes from Codex's documentation of 28/09/2026; a few fields are not confirmed (see below).

1. Add the MCP server in Codex's configuration, <code>~/.codex/config.toml</code>:
   [mcp_servers.codelux] url = "http://localhost:8766/mcp"
   This form is taken from Codex's MCP documentation and not verified by us on every version: if Codex does not list the tools, check the exact syntax there.
2. Instruction file: <code>AGENTS.md</code>. The block is written by the session-start hook, or by hand with the command above.
3. Copy this file to <code>&lt;project&gt;/.codex/hooks.json</code> (or to <code>~/.codex/hooks.json</code> for every project), replacing <code>CODELUX_PLUGIN</code>:
   { "description": "Codelux hooks for Codex. Copy to <repo>/.codex/hooks.json (or ~/.codex/hooks.json) and replace CODELUX_PLUGIN with the absolute path of the folder that holds scripts/. Same scripts as the Claude Code plugin; plain stdout is added as context, exit 2 on acquire blocks the edit with the stderr reason. PreToolUse/PostToolUse on every tool (.*) feed the procedure trace (377). See hooks/OTHER-AGENTS.md for the fields we could not verify.", "hooks": { "SessionStart": [ { "matcher": "startup|resume|clear|compact", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-start.sh\" --agent=codex", "timeout": 10, "additionalContextLimit": 12500 } ] }, { "matcher": "startup|resume|clear|compact", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" start --agent=codex", "timeout": 5 } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/prompt-memory.sh\" --agent=codex", "timeout": 5 }, { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" prompt --agent=codex", "timeout": 5 } ] } ], "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|apply_patch", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" acquire --agent=codex", "timeout": 10 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" pre --agent=codex", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit|apply_patch", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" release --agent=codex", "timeout": 10 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" post --agent=codex", "timeout": 5 } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" stop --agent=codex", "timeout": 5 } ] } ] } }
4. Restart Codex.

Not confirmed

• The names of the edit tools: the documentation's example is <code>Edit|Write</code> (file edits through <code>apply_patch</code>); we match <code>Edit|Write|MultiEdit|apply_patch</code> to be safe.
• The field that carries the edited path for <code>apply_patch</code>. The script looks for <code>file_path</code>, <code>notebook_path</code> or <code>path</code>; if Codex sends only the patch text, the lock does nothing (it never blocks).
• The unit of <code>timeout</code> (we assume seconds) and a project-folder variable (the scripts use the working directory, or <code>CODEX_PROJECT_DIR</code> if set).
• Whether Codex sends a <code>session_id</code> to the hooks. Without it the session tracking is skipped, and the MCP calls get one code per connection.

Gemini CLI

Experimental. The hooks format comes from Gemini CLI's reference of 28/09/2026; a few fields are not confirmed (see below). Everything goes in <code>&lt;project&gt;/.gemini/settings.json</code> (or <code>~/.gemini/settings.json</code>).

1. Add the MCP server:
   { "mcpServers": { "codelux": { "httpUrl": "http://localhost:8766/mcp" } } }
   This form is taken from Gemini CLI's MCP documentation and not verified by us on every version: if the tools do not appear, check the exact syntax there.
2. Instruction file: Gemini reads <code>GEMINI.md</code>, not <code>AGENTS.md</code>. Either point it at <code>AGENTS.md</code> in the same settings file, or copy the block into <code>GEMINI.md</code>:
   { "contextFileName": "AGENTS.md" }
   The setting is called <code>contextFileName</code> in our plugin notes; if your version of Gemini CLI names or nests it differently, check its settings reference.
3. Merge this <code>hooks</code> object into the same file, next to the keys above, replacing <code>CODELUX_PLUGIN</code>. The scripts run with <code>--json</code> because Gemini wants only JSON on stdout:
   { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "name": "codelux-memory", "description": "Codelux: project memory in context at session start; refreshes the AGENTS.md/GEMINI.md block", "command": "bash \"CODELUX_PLUGIN/scripts/session-start.sh\" --json --agent=gemini", "timeout": 10000 } ] }, { "hooks": [ { "type": "command", "name": "codelux-session", "description": "Codelux: session code and usage tracking (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" start --agent=gemini", "timeout": 5000 } ] } ], "BeforeAgent": [ { "hooks": [ { "type": "command", "name": "codelux-prompt-memory", "description": "Codelux: relevant memory for this prompt as additionalContext (nothing when nothing is found)", "command": "bash \"CODELUX_PLUGIN/scripts/prompt-memory.sh\" --json --agent=gemini", "timeout": 5000 }, { "type": "command", "name": "codelux-session-prompt", "description": "Codelux: count the prompt; rarely one hint about the last turn", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" prompt --json --agent=gemini", "timeout": 5000 } ] } ], "BeforeTool": [ { "matcher": "write_file|replace|edit", "hooks": [ { "type": "command", "name": "codelux-lock-acquire", "description": "Codelux: take the file lock (local + Team) before an edit; exit 2 with the reason when refused", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" acquire --agent=gemini", "timeout": 10000 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "name": "codelux-session-pre", "description": "Codelux: start of every tool call for the procedure trace, file read (path+hash), MCP call announcement; rarely one hint as additionalContext", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" pre --json --agent=gemini", "timeout": 5000 } ] } ], "AfterTool": [ { "matcher": "write_file|replace|edit", "hooks": [ { "type": "command", "name": "codelux-lock-release", "description": "Codelux: release the file lock after an edit", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" release --agent=gemini", "timeout": 10000 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "name": "codelux-session-post", "description": "Codelux: one row of the procedure trace (tool, essential arguments, response size, duration; never contents)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" post --agent=gemini", "timeout": 5000 } ] } ], "AfterAgent": [ { "hooks": [ { "type": "command", "name": "codelux-session-stop", "description": "Codelux: read the new usage numbers (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" stop --agent=gemini", "timeout": 5000 } ] } ], "SessionEnd": [ { "hooks": [ { "type": "command", "name": "codelux-session-end", "description": "Codelux: close the task and write the usage report (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" end --agent=gemini", "timeout": 10000 } ] } ] } }
4. Restart Gemini CLI.

Not confirmed

• <code>SessionStart</code> does not list <code>additionalContext</code> among its fields in the reference; the script sends it anyway. If it is ignored, the block in <code>AGENTS.md</code> / <code>GEMINI.md</code> still carries the state.
• The names of the built-in edit tools (we assume <code>write_file</code>, <code>replace</code> and <code>edit</code>) and the path field inside their input (<code>file_path</code>). If they differ, the lock does nothing and never blocks.
• Whether Gemini sends a <code>session_id</code> to the hooks (same consequence as for Codex), and a project-folder variable: none is documented, the scripts use the working directory.

Cursor

Cursor has no hooks: everything goes through the MCP server and a rule that tells the agent what to call.

1. Add the server to <code>.cursor/mcp.json</code> in the project (or <code>~/.cursor/mcp.json</code> for every project):
   { "mcpServers": { "codelux": { "url": "http://localhost:8766/mcp" } } }
2. Create the rule <code>.cursor/rules/codelux.mdc</code>:
   --- description: Codelux project memory alwaysApply: true --- This project uses Codelux (MCP server "codelux"). - At the start of a task call memory_get with no arguments and continue from it. - Before relying on a name or a path, check it with code_query or code_context. - Write files through code_edit, so the file is locked against other agents and the edit lands on the Timeline with its diff. - When you finish, call memory_set once: summary, status, next, traps, decisions.
3. Restart Cursor, or reload its MCP servers.

Say who you are: one name on every channel

Every agent gives itself a short codename (<code>w375</code>, <code>tree-blocks</code>) and passes it on every channel: MCP argument <code>agent</code>, REST <code>agent=</code> or <code>X-Codelux AI-Agent</code>, CLI <code>--agent=</code>. Codelux AI joins it to the host's own session (and subagent), so the edits seen by the hooks, the MCP calls and the REST or CLI calls are ONE row on the timeline: the name as the title, the host (Claude Code, Claude Code subagent, Codex, Gemini CLI, Cursor, REST, Other agent) beside it, the session id in the tooltip. A session that has not said its name yet shows as <i>waiting for its name</i> and takes it at its first call that gives it, also for what it did before. With the Claude Code plugin nothing else is needed; other hosts can pass the session too, see <a href="#" data-doc-go="curl">REST / cURL</a>.

Check that it works

After a short session, the agent's memories, edits and locks are on the timeline with its name. Read them back over REST:

🖥 IDE Setup (MCP)

Codelux AI speaks native MCP. One config line connects it to any MCP-capable editor or agent. Without the Claude Code plugin there are no hooks: the agent reads its memory when it calls <code>memory_get</code> (or from the <code>AGENTS.md</code> block) and the lock is taken by <code>code_edit</code> instead of around its own editor.

Claude Code (without the plugin)

The <a href="#" data-doc-go="hooks">plugin</a> is the recommended way. By hand, add to <code>.mcp.json</code> in your project root (or <code>~/.claude.json</code> for all projects):

Cursor

Add to <code>.cursor/mcp.json</code> in the project (or <code>~/.cursor/mcp.json</code> globally):

VS Code (Copilot Chat)

Add to <code>.vscode/mcp.json</code> in your workspace:

Windsurf

Add to <code>~/.codeium/windsurf/mcp_config.json</code>:

JetBrains (AI Assistant)

Settings → Tools → AI Assistant → Model Context Protocol → Add server → URL <code>http://localhost:8766/mcp</code>.

Zed

Settings → <code>context_servers</code> → add Codelux AI with the same URL.

Any other MCP client

Codelux AI exposes standard MCP at <code>http://localhost:8766/mcp</code> (streamable HTTP; the older SSE transport stays at <code>/sse</code>). If your tool speaks MCP, it works. Every transport lists the 8 core tools; add <code>?profile=full</code> to the URL to list the rest as well.

🧰 MCP Tools

8 tools, listed by every transport by default. Once connected, your AI picks the right one; with the Claude Code plugin the first read and the file lock happen from hooks, without a call.

Memory

Notes

Check against the code

Writing and agents

A session with the plugin

1. Session starts — the hook puts the newest memory in context: what was done, what is next, the traps
2. You type a prompt — if a codemap, a fact or a decision matches, the hook adds it; otherwise nothing
3. <code>code_query</code> / <code>code_context</code> — check a name or a dependency before touching it
4. Edit with Claude Code's own tools — the hook takes the lock before and releases it after
5. <code>notes_set</code> — a todo for you, a form when it needs an answer, a decision and the why
6. <code>memory_set</code> — the session closes with its memory; the Stop hook reminds the model if it forgot

Every one of these steps is an event on the <a href="#" data-doc-go="timeline">timeline</a>.

🕒 Timeline

The timeline is the record of everything that happens on a project, emitted by Codelux AI itself: you never write to it, and nothing on it is lost — a delete is an event that keeps the previous content.

What lands on it

Where to read it

• <b>Timeline tab</b> of the dashboard: events in order, filters by type, topic, author, period and file; a click opens the original — the note, the memory, the file diff, the commit.
• <b>For the agent:</b> <code>memory_get</code> with <code>events: true</code>, with the same filters.
• <b>On a team:</b> every event reaches every member's machine, encrypted with the team key, with who did it.

🌐 REST / cURL

Every tool is also a plain HTTP endpoint. Scripts, CI pipelines, custom tooling, legacy editors: anything that can make an HTTP call can use Codelux AI.

Base URL

<code>{project}</code> is the name of an indexed project. List them with <code>/api/projects</code>.

<b>Say who you are.</b> Every call below that reads or writes the project must name the calling agent, the same way on MCP, REST and the CLI: <code>agent=&lt;codename&gt;</code> in the query or in the JSON body, or the header <code>X-Codelux AI-Agent: &lt;codename&gt;</code> (CLI: <code>--agent=&lt;codename&gt;</code> or the <code>CODELUX_AGENT</code> variable; MCP: the <code>agent</code> argument, filled by the client). Without it the call is refused with <code>400 agent required</code>; with it, the timeline shows the agent by name. To call an MCP tool by its own name and arguments: <code>POST /api/project/{project}/tool/{name}</code>.

<b>Same agent, same row.</b> To tie a REST call to the agent's own session (the one its hooks report), add <code>session=&lt;host session id&gt;</code> and <code>provider=claude-code|codex|gemini|cursor|other</code>, plus <code>subagent=&lt;id&gt;</code> inside a subagent; or the headers <code>X-Codelux AI-Session</code>, <code>X-Codelux AI-Provider</code>, <code>X-Codelux AI-Subagent</code> (CLI: <code>--session</code>, <code>--provider</code>, <code>--subagent</code> or the variables <code>CODELUX_SESSION</code>, <code>CODELUX_PROVIDER</code>, <code>CODELUX_SUBAGENT</code>). With the Claude Code plugin the session start sets <code>CODELUX_SESSION</code> and <code>CODELUX_PROVIDER</code> in every Bash command, and the hook reads the name in a command that calls Codelux AI: the name alone is enough. Without any session id, the agent is one row per name, shown as <i>Other agent</i>.

Search & reading

Analysis

Memory, notes & timeline

Writes & git

Management

⌨️ CLI Commands

The binary also serves as a CLI — useful for quick checks without leaving the terminal.

Run <code>codelux.exe</code> (Windows) or <code>./codelux</code> (Linux) without arguments to start the server. The following sub-commands are available for terminal use:

Read & search

Memory & notes

Writes & index

Example session

📊 Web Dashboard

Codelux AI includes a built-in web dashboard at <code>http://localhost:8766</code> — manage every project from the browser, even when Codelux AI runs on a remote server.

Tabs

Server / headless install

Run Codelux AI on a server and open the dashboard from any browser: web login, multi-project sidebar, per-project config.

Projects and plans

Codelux AI keeps watching and indexing <b>every</b> project you register, on every plan — the plan decides what you can act on, not what is kept up to date. On <b>Free</b> one project is active at a time: the others show an <i>Activate this project</i> action instead of their tabs, and the tools stay disabled until you switch, which you do from the app. On <b>Multi</b> and <b>Team</b> every project is active at once, with no activation limit.

👥 Teams

The Team plan shares one project between the people you invite. Memories, notes, the timeline, chat and edit history travel between machines as encrypted events; the file semaphore and who is online are coordinated live. Code and index never leave anyone's machine, and the key that protects the shared data never reaches us.

Where everything lives

1. Buy the seats

The Team plan is a yearly subscription of the team owner, priced per seat with a minimum seat count — both are on the <a href="/pricing">pricing page</a>. Seats count <b>distinct people</b> across every team you own, the owner included: the same person in two of your teams uses one seat. Members join with their own account and need no plan of their own.

2. Create the team on the site

In the <a href="/console">Console</a>, open <b>Teams → New Team</b>: give it a name, pick <b>one project</b> from your account's project list, add the members' email addresses and choose how the team shares files (<b>Git clones</b> or <b>Shared folder</b>, see step 7). One team = one project; create another team for another project. Each member receives an invitation by email — without an account yet, the link takes them to registration first — and accepts it from their own Console. Nothing about the team's contents is ever visible on the site.

3. The owner's app makes the keys

The owner's Codelux AI generates, once, a <b>master key</b> (256 random bits) in <b>Settings → Keys</b> and keeps it sealed on that computer. The key of each team is <b>derived</b> from it, version by version; our server keeps only a public check value per team and version, which reveals nothing about the key. The owner can show and copy the master key behind a confirmation, and export it to a file (protected with a passphrase, recommended) to set up another computer. No button on the site or in the app ever sends a key to us.

4. Hand the key to the members

• <b>Copy team key</b> — in Settings → Keys the owner copies the key of one team (it starts with <code>cdx-t-</code>) and sends it to that team's members over a channel they trust (in person, a message, a password manager). It opens only that team; the master key is never given to members.
• <b>Paste the team key</b> — the member pastes it in the banner of the team's project; spaces, dashes and case are ignored, and the app checks it against the server's check value before keeping it (a wrong key is refused at once).

Every member keeps every key version they receive, so events written before a rotation stay readable on their machine.

5. Point each machine at the project folder

Shared projects appear in the sidebar under <b>Shared with you</b>, grouped by team. On the owner's machine the folder is taken from the project list; on every other machine the member chooses <b>Set folder on this machine…</b> and gives the path of their clone (Git clones) or of the shared folder (Shared folder). The path is recorded per machine, so the same project can live at different paths on different computers. A shared project is ready once the machine has both the folder and the key.

6. The Team tab

When the selected project belongs to a team, the dashboard gains a <b>Team</b> tab: the chat with its channels — the team channel, direct messages between two members and groups created by the owner or an admin — the member list with who is online, and the file locks showing who is editing what. Notes, journal, facts and CodeMap carry the author of each entry and a filter (<i>All · Me · a member</i>). Without the key the tab offers only <i>Paste the team key</i>.

7. Git clones or Shared folder

In both modes the rule is the same: writes to the shared project go through only while the realtime service that holds the locks is reachable. When it is not, edits to the shared project through the Claude Code hook on Edit and Write are refused with a clear message, never applied blindly.

8. Members on the Free plan

A member covered by the owner's seats is entitled to the <b>Team build</b>: the Downloads section of their Console shows it as <i>Team build (covered by &lt;team&gt;)</i>. They download it, sign in with their own account and work on the shared project with locks, presence and chat; their own projects follow their own plan (on Free, one active project per machine). The public Free build has no realtime client: with the folder and the key it can read the shared knowledge, but every write on the shared project answers <i>Team build required</i>.

9. Removing a member, rotating the key

Members are removed from the site; removal cuts their access to new events at once, but whatever already reached their machine stays there. When that matters, the owner presses <b>Turn key</b> in Settings → Keys: the version number goes up and new data is sealed with the new key; the members who stay keep reading the old data and get the new key from the owner (<i>Paste the team key</i>). Turn it too whenever you suspect the key has leaked.

10. Machines, offline, and when the plan lapses

• <b>One Codelux AI per machine.</b> Signing in with the same account on another machine takes over; the previous one is signed out (the last login wins). This holds for every member.
• <b>Offline.</b> The app checks in with the licence server every minute; after three failed checks it is offline and, until the next successful one, writes to shared projects are refused — the same fail-closed rule as a realtime outage. There is no offline grace period on any plan.
• <b>Plan lapsed or seats exceeded.</b> The team goes dormant: its shared project is no longer authorised for the members, who see <i>Plan lapsed</i>. Nothing is deleted and no key is touched — the keys stay on every machine, the events stay on the server, and everything resumes at the renewal. Meanwhile the owner can still remove members or delete the team.
• <b>Deleting the team.</b> Removes every encrypted event and all team metadata from our servers. What each member already has on their machine stays there and remains theirs.

11. Roles: Admin, Manager, Member

<b>Admin</b> — buys the seats and administers the organization from the <a href="/console">Console</a>: creates teams, invites people, assigns each person as <b>Manager</b> or <b>Member</b> of each team, names the organization <b>Admins</b>, sets up SSO and SCIM. <b>Manager</b> — coordinates a team in the app: <b>Tasks</b> (key, title, assignee, start and due date, status, checklist, planned and actual %) as a list, a board and a Gantt, shared end-to-end encrypted like notes; <b>Generate reports</b> builds one standup per member per day from the timeline only — memories, checkpoints, closed todos, file edits, locks, tasks moved — never from the chat, and the manager confirms the actual %; <b>People</b> of his team with agents seen, last activity and a per-member download (no chat) that is itself recorded on the timeline; usage and costs per member. <b>Member</b> — works with agents and sees the team plan, their own plan, usage, the timeline and the chat. A person can hold several roles. In the app the project list is grouped: personal projects, then the teams you are a member of, then the teams you manage. Hosted by us, a team has Codelux AI planning, chat, standups, timeline, memory, semaphore, usage, costs and audit — and no connector.

12. Sign-in, SSO, SCIM and organisation admins

Every account can sign in with email and password plus an email code, or with Google, GitHub or Slack. The owner of a Team plan can connect the company's identity provider over <b>OIDC or SAML 2.0</b> for verified domains, require SSO for them (the owner keeps every sign-in method as the way back in), and issue a <b>SCIM 2.0</b> token: a person deactivated in the provider is removed from all the owner's teams, signed out everywhere, and a key rotation is requested. In <b>Admins</b> the owner names <b>organisation admins</b>, who administer all of the owner's teams but cannot change billing or delete the organisation. The documents for your IT review are on the <a href="/security">Security</a> page.

13. Integrations: the company hub

Integrations are not part of our hosted service. With the company hub, <code>codelux-hub</code> — a program your company runs, included in Team and Enterprise — a team also gets Jira, Linear, Asana, Azure Boards, GitHub, GitLab and Slack notifications, executed by the hub and always on. The Admin connects each provider once for the organization; the Manager of a team picks, among them, the team's Jira project, repository or Slack channel, without handling any token. An organization is either entirely on our hosted service or entirely on its hub, and a migration package moves a team from one to the other. Register and download the hub from <b>My account › Downloads › Hub</b> in the <a href="/console">Console</a>. We never see your code, memories, timeline, nor your tokens.

What we do not do

• We never receive, store or forward the team key. There is no escrow and no recovery: if every member loses it, the encrypted events are unreadable — for you and for us.
• We cannot read memories, notes, the timeline, CodeMaps, edit history or chat. We do not know what kind of event it is or which file it refers to.
• We do not upload code or index files, on any plan.
• We do not make direct messages private towards the team — see step 6.
• The planning and chat service is hosted by us and has no connector. A company that wants integrations runs its own hub, <code>codelux-hub</code> (included with Team): it executes Jira, Linear, Asana, Azure Boards, GitHub, GitLab and Slack notifications with tokens that stay on your side. The DPA template, the security questionnaire and the deployment guide are on the <a href="/security">Security</a> page; a signed DPA is available on request.