naumudocs

Repo quickstart

Wire a shared repository into your team's Naumu space from your coding agent - one pasteable prompt connects you, whitelists teammates, and opens a review PR.

Updated 8 min read

Turn a shared repository into a front door for your team's memory. One pasteable prompt, run from your coding agent, connects you to Naumu, points the repo at your team's space, whitelists the people who ship code, and opens a pull request the team can review. After it merges, each teammate's agent finds the .naumu file and offers to connect; they sign in and join by their whitelisted email - see Naumu for your repository for the whole story.

This page is for a developer wiring a repo into Naumu. It builds on the local coding agent connection - the prompt runs that setup for you if the tools aren't connected yet.

The prompt

Paste this to your coding agent - Claude Code, Codex, or Cursor. It asks before running each command and never commits directly to a protected branch.

Paste the prompt text, not a link to this page. An agent pointed at the URL has to fetch it as untrusted web content, so it stops for a permission check on nearly every step and may refuse to follow instructions it found on a web page at all. The copy button (or the "Open in Claude Code" button on the Your agents settings page) hands it the text directly, which is what it expects.

If you're already in Naumu, you can skip the copy-paste: tell the chat you work in a coding agent and Naumu replies with a setup card that opens this same prompt straight in Claude Code, Codex, or Claude Code for VS Code. It's the identical prompt either way.

text
Set up Naumu for this repository. Ask me before running each command, and never commit directly to a protected branch.
1. Connect: if Naumu MCP tools are missing, add the server for this tool, then sign in via the browser (creating my account if needed): Claude Code: claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp - Codex: codex mcp add naumu --url https://naumu.ai/api/mcp then codex mcp login naumu - Cursor: add "naumu": {"url": "https://naumu.ai/api/mcp"} under mcpServers in .cursor/mcp.json
2. Install the Naumu skill: npx skills add naumu-ai/skills. If .gitignore ignores .agents/ or .claude/, add unignore rules so the skill files can be committed.
3. Call naumu_whoami and use its space list (else naumu_list_graphs) to pick an existing space, or offer to create one with naumu_create_graph.
4. Find teammates from git history - run this exact command, do not improvise the filter: git log --all --since=90.days --format='%ae %an' | grep -viE '^noreply@|dependabot|github-actions|\[bot\]' | sort | uniq -c | sort -rn - then tag each address TEAM (company domain), CONFIRM (public provider like gmail.com) or ASK (users.noreply.github.com). Show me all groups; ask me for ASK people's sign-in emails; never whitelist a CONFIRM address without my explicit per-address confirmation.
5. After I confirm, call naumu_whitelist_members with those emails and repoInit true. They auto-join when they sign in with that email; no invites are sent.
6. Ask me what to call the tracking topic (suggest work-log, kebab-case). Call naumu_list_topics and create it if missing with notifyOn "people" (automated posts stay silent), then create .naumu in the repo root with the space id and slug and the topic name and id: { "space": "<space id>", "slug": "<space slug>", "tracking": { "topic": "<name>", "topicId": "<topic id>", "commitTrailer": true } } - leave commitTrailer true, don't ask.
7. Append to AGENTS.md as a MANDATORY rule: at the start of any build, fix, refactor or feature task, run naumu_search for prior context, then open a work-log thread with naumu_delegate passing topicIds [tracking.topicId from .naumu] and a short "Starting work:" brief, and keep the returned threadId. Post follow-ups into that threadId on decisions, pivots and blockers, and a bulleted summary when done. Add the trailer Naumu-Thread: https://naumu.ai/spaces/<slug>/chat/<threadId> to every commit. Never block work on a failed Naumu call. If Naumu MCP tools are missing, offer setup once, never auto-run: npx skills add naumu-ai/skills, then naumu_resolve_admission with the space id.
8. Open a pull request with these changes plus the installed skill files (.agents/skills/naumu and its .claude/skills/naumu symlink) so the team can review.
9. Offer to seed the space with this repo's architecture and glossary, plus key people, projects and decisions from my connected tools.

What it does

The prompt is an installer. It connects your agent to Naumu over the remote MCP server (creating your account in the browser if you don't have one), installs the day-to-day skill, and does the repo setup as an agent task: pick or create the team space, scrub git history for teammates, write two small files, and open a PR. Nothing secret is committed - the .naumu file holds the space ID, which is an identifier, not a credential.

The nine steps

  1. Connect. If Naumu's MCP tools aren't available yet, the agent adds the server for your tool and you finish sign-in in the browser - which doubles as signup for a new account. Codex signs in with codex mcp login naumu. A newly added server usually loads only in a new session, so you may need to restart the agent and paste the prompt again.
  2. Install the skill. npx skills add naumu-ai/skills adds the read-and-write loop your agent uses on every task. If your .gitignore ignores .agents/ or .claude/, the agent adds unignore rules first so the skill files can be committed.
  3. Pick a space. The agent calls naumu_whoami; if you already have spaces it asks which one, otherwise it creates one.
  4. Scan git history. It lists authors from the last 90 days, drops bots, and shows you the list - public-provider addresses (gmail and similar) are grouped separately for you to confirm one by one. GitHub's private users.noreply.github.com addresses can't sign in to anything, so the agent asks you for those people's real sign-in emails instead.
  5. Whitelist teammates. After you confirm, it records the emails; whitelisted teammates auto-join the space when they sign in - no invite emails are sent.
  6. Write .naumu. The agent asks what to call the tracking topic (suggesting work-log), creates it in the space if it doesn't exist - set to notify on people's messages only, so nobody is pinged by the automated entries - and writes a tiny config at the repo root holding the space ID and slug plus the topic's name and ID. The ID matters: work-log entries are filed by topic ID, so without it they would land in the space-wide misc feed.
  7. Update AGENTS.md. A short mandatory rule tells every teammate's agent to search the space at the start of a task, open a work-log thread filed into the tracking topic, post follow-ups on decisions, pivots and blockers, post a summary when done, and put the thread link in every commit as a Naumu-Thread: trailer. A failed Naumu call never blocks the work. If the tools are missing, the agent offers setup once - offer only, never auto-run.
  8. Open a PR. The changes go up as a pull request so the team reviews and merges them - the human merge is the team's consent. The installed skill files go in too (.agents/skills/naumu and its .claude/skills/naumu symlink, which git tracks fine), so a fresh clone gets skill discovery without re-running the installer.
  9. Offer to seed. The agent offers to summarize the repo's architecture and glossary into the space, plus the key people, projects and decisions it can see in your other connected tools (an issue tracker, docs), so the first searches return something useful. It asks first, like every other step.

Who gets in

Admission is by identity, checked against verified email when someone signs in - never by a token in the repo.

  • Whitelist (instant). The teammates you confirmed in step 5 join the moment they sign in with that email.
  • Domain wildcard (instant). An admin can set patterns like @yourcompany.com in the space's humans panel; public-provider domains are blocked, so a @gmail.com wildcard is impossible.
  • Request to join (fallback). No match means the newcomer's request lands in the space, and any member approves it with one click. This covers the common case where someone's git email differs from their sign-in email.
  • Seat limits. When a space is at its plan's member cap, a would-be auto-join surfaces as a pending request instead, so an admin can make room or upgrade. See Plans and billing for the caps.

Related

Anything missing?
Tell us what would make these docs better.
CodexAgent skills