Quick Start

What You Need

  • An AI tool with MCP support: Claude Code, Claude Desktop, GitHub Copilot, Cursor, n8n, or any MCP-compatible client
  • Path-specific extras come up in Step 2 — invited users need nothing more; “build your own” needs a GitHub account (or we’ll manage the repo for you on Free/Expert)

Step 1: Connect your AI tool

Same for every flow — auth and tool connection. Path-specific setup happens in Step 2.

Claude Code

Run this once from anywhere — it registers aswritten across all your projects:

claude mcp add --scope user --transport http aswritten https://api.aswritten.ai/mcp

Open Claude Code in any project directory and run /mcp. Select aswritten to authenticate (opens a browser). Restart Claude Code so the connection takes effect.

Claude Desktop

Settings → Connectors → Add custom connector. Name it aswritten. Server URL: https://api.aswritten.ai/mcp. Press Connect and authenticate in the browser.

Two things have to be true for Claude Desktop to work properly. Both matter — neither alone is enough:

  1. A Project’s custom instructions must contain the perspective’s ASWRITTEN.md (or CLAUDE.md) content. Step 2 covers what to paste depending on your path. A Project without the paste is just an empty container — Claude will see the aswritten tools but won’t know the workflow, conviction rules, or citation conventions. The experience will be flat.
  2. You have to start every chat from inside the Project (sidebar → click the project → New Chat). Custom instructions only load for chats that start inside the Project. Chats started from the main screen connect to the aswritten tools but skip the workflow instructions, and the experience is significantly worse.

You can type aswritten in any chat to invoke the connector directly — that works without a Project — but the workflow steering only kicks in when both conditions above are met. Always start from a Project.

Other MCP-compatible tools (GitHub Copilot, Cursor, n8n)

Add an MCP server with URL https://api.aswritten.ai/mcp. Authenticate with your email. Restart your AI tool so the connection takes effect.

Login vs. sign-up. When the browser window opens to authenticate:

  • If you were invited to a team — log in with the email from your invite. You’re already on your team’s tier; there’s nothing to pick.
  • If you’re starting fresh — sign up and pick a tier (Free to try, Expert to build your own, Team to roll out to others — see Pricing).

Step 2: Pick your path

Three flows. Pick the one that describes you.

Path A: I was invited to a team perspective

The most common case for pilot users. Your team admin has already set up the perspective — there’s nothing to scaffold, no first-memory interview, no GitHub App to install. You just need to point your AI at it.

For Claude Desktop:

  1. Sidebar → Projects → New Project. Name it for your team.
  2. Get the contents of your team’s knowledge repo CLAUDE.md (or ASWRITTEN.md). If you have repo read access, open it on GitHub. If you don’t, ask your team admin to paste it into Slack or email.
  3. Paste the contents into the Project’s custom instructions.
  4. Always start chats from inside the Project (see Step 1 Desktop callout for why).

For Claude Code:

  1. Clone your team’s knowledge repo locally: git clone <repo-url>.
  2. Start Claude Code from inside the cloned directory. The system prompt loads automatically.

Then ask away. Type aswritten to load the perspective and ask whatever you’d ask a senior person on the team. Citations show where each answer came from.

No GitHub access? That’s the common case for team members on Team-tier perspectives. You don’t need GitHub to use the perspective — being added to the team (a “license”) is what gives you load/ask/remember access. The only things that need GitHub access are reviewing/merging the PRs that result from saving memories (the team admin usually does this) and the Claude Code workflow that clones the repo locally. If you’re using Claude Desktop and don’t have repo access, ask your team admin to paste the CLAUDE.md content directly into Slack or email.

Path B: I want to try with a public perspective

You don’t have a team and you’re not building your own — you just want to see how aswritten works. Free tier covers this.

  1. Sign up Free in the auth window from Step 1.
  2. Get a perspective share ID — ask whoever pointed you here for one, or import one from someone you know is using aswritten.
  3. In your AI tool, type aswritten and load the perspective by ID.
  4. Ask questions. Citations and gaps work the same way they would on a perspective you built yourself.

Path C: I’m building my own perspective from scratch

Sign up Expert ($81/mo) or Team ($400/mo) in the auth window from Step 1. Then in your AI tool:

  1. Type aswritten. Claude walks you through:
    • Connect GitHub — install the aswritten GitHub App and select which repos to connect (Free/Expert: we manage the repo for you; Team: connect your own GitHub org)
    • Initialize — switch to your current repo and scaffold the aswritten files (ASWRITTEN.md, GitHub Actions workflows) via a commit to your default branch
    • First memory — Claude interviews you about the project and saves your first memory
  2. After the first memory is saved, extraction runs (~2-3 minutes) and a PR opens.
  3. Review the PR to see exactly what knowledge was extracted — every fact traces back to a specific memory from a specific person.
  4. Merge the PR. Your perspective updates on next load.
  5. From here, the pattern repeats: decisions come up → Claude offers to save them → extraction → PR → merge.

If you’re using Claude Desktop, also paste the scaffolded ASWRITTEN.md content into a Project’s custom instructions (same as Path A Desktop steps; the source is your repo’s freshly-scaffolded file).

What Happens During Onboarding (Path C)

Claude walks you through this entire process, but here’s what to expect:

First memory creation. Claude interviews you about your project — what it does, key decisions you’ve made, who’s involved, what’s in progress. You talk naturally; Claude drafts a memory document from the conversation and asks you to approve it before saving. The memory is committed to a branch in your repo under .aswritten/memories/.

Extraction pipeline. After you approve the memory, extraction runs synchronously (~2-3 minutes). An LLM reads your memory and extracts structured knowledge (facts, decisions, actors, relationships) as RDF transactions. The memory and transactions are committed together atomically. A PR opens with the extracted knowledge.

PR review and merge. The PR shows exactly what was extracted — you can see which facts the system pulled from your words. Review and merge when ready. This is your audit trail: every piece of organizational knowledge traces back to a specific memory from a specific person.

Perspective. After merging, Claude loads your perspective — a structured snapshot of everything your organization knows. This is what grounds Claude’s responses going forward. Instead of generic answers, Claude draws on your documented decisions, strategy, and context.

Introspect. Claude can analyze what’s documented vs. what’s missing. It surfaces knowledge gaps by domain and suggests questions to fill them. This is how your expertise grows intentionally — not just from what you happen to mention, but from what the system identifies as undocumented.

The loop. From here, the pattern repeats naturally: you work, decisions come up, Claude offers to save them, extraction runs, your perspective updates, and Claude’s behavior shifts to reflect what you’ve documented. Each memory makes every future session smarter.

Daily Use

Once set up, Claude automatically loads your perspective at session start. As you work:

  • Decisions come up → Claude offers to save them as memories
  • You ask questions → Answers are grounded in your documented knowledge, not hallucinated
  • Gaps surface → Claude identifies what’s undocumented and suggests who to ask
  • Knowledge compounds → Each memory makes every future session smarter

For more on getting good answers from a perspective, see Asking the Perspective Well.

Multiple Repos

aswritten works across repos and organizations. Use switch-repo to change which repo Claude is working with. Each repo stores its own perspective.

Upgrading from the Old Setup

If you previously had aswritten configured via .mcp.json and CLAUDE.md in a repo:

  1. Delete the old aswritten entry from your .mcp.json
  2. Remove any aswritten-related instructions from CLAUDE.md
  3. Follow the setup steps above — the new flow handles everything

The init step will re-scaffold ASWRITTEN.md and .mcp.json automatically.

Feedback

Share interesting sessions via Claude Code’s /export command. Bug reports and feedback welcome — the MCP proxy auth is brand new.

This site uses Just the Docs, a documentation theme for Jekyll.