Workstate Docs

Quickstart ​

This guide takes you from signing in to your first cited search and your first ledger entry. It takes about 15 minutes, plus the time your first sync needs. It uses Claude Code as the agent. Connect your agent covers other clients.

What you need ​

  • An invitation. Workstate is invite-only for now. An invitation names an email address, and you sign in with a GitHub account that has verified that address. Workstate does not send invitation emails, so the person who invited you tells you.
  • The owner or admin role, to add a source. The first person in a new account is its owner.
  • Something to index: GitHub repositories on an organisation you administer or on your personal account, or files on your computer.
  • Claude Code, and a project folder to run it in.

Joining a teammate's account?

Your invitation sets your role and the namespaces you can reach. Members cannot add sources, so if you are a member, use the sources already in your namespace and go on to step 5. Team & invites has the details.

1. Sign in ​

  1. Go to https://console-uat.workstate.io and select Continue with GitHub.
  2. Approve the request on GitHub. Workstate asks only for your GitHub profile and email addresses (read:user and user:email). It gets no access to your repositories.

If you see "Workstate is invite-only for now", none of your GitHub account's verified email addresses has been invited. Verify the invited address in your GitHub settings, or ask for an invitation to an address you have verified. Then sign in again.

A console session lasts 7 days.

2. Check your namespace ​

A namespace is a separate index with its own sources, search and ledger. A new account starts with one called Personal.

The namespace switcher at the top of the sidebar shows which namespace you are in. Everything you add in the next steps goes into that namespace.

If the console says No namespace yet, you cannot reach any namespace. An owner or admin can create one: open Namespaces, type a name and select Create. A member can ask an owner or admin to give them one on the Team page. See Namespaces.

3. Add a source ​

Open Sources. Under Add a source, choose GitHub for code, or Upload files for documents and for teams that do not keep their work on GitHub.

Option A: GitHub ​

  1. Select GitHub, type a name for the source (for example, "Our code"), and select Install on GitHub.
  2. On GitHub, choose the account and the repositories to share, and confirm.
  3. GitHub sends you back to the new source's page, which confirms the connection. The first sync starts by itself.

Workstate reads only the default branch of each repository you share. You can change which repositories are shared on GitHub at any time. See GitHub.

Remove secrets first

Workstate does not filter secrets out of GitHub repositories. It skips hidden files such as .env, but a password, token or key committed in any other file is indexed, and everyone in the namespace can find it. Do not share a repository that holds committed secrets until you have removed them.

Option B: Upload files ​

  1. Select Upload files, type a name (for example, "Team handbook"), and select Create source. Leave Each top-level folder is a repository cleared unless you are uploading a set of project folders. You cannot change this setting later.
  2. On the source's page, drop files or folders onto the upload area, or use Choose files or Choose a folder. Then select Upload.

Workstate accepts Markdown, text and code, PDF, and Word, Excel and PowerPoint files (.docx, .xlsx, .pptx). It refuses private keys and .env files. Each upload starts a sync. See Upload files and Limits & defaults.

4. Wait for the first sync ​

The source's status moves from Queued to Syncing to Up to date. While it syncs, the source's page shows the progress of each repository, with a history of syncs below.

The first sync reads everything, so it takes the longest. A large repository can take a few minutes. Files become searchable as they are indexed, but wait for Up to date before you judge the results.

If the status shows Failed, open the source to read the error.

5. Create an API key ​

An API key lets an agent act as you, and everything it records is attributed to you.

  1. Open API keys.

  2. Under Create a key, describe what the key is for (for example, "claude-code on the laptop") and select Create key.

  3. Select Copy key, and store the key now. Workstate shows it once and keeps only a hash of it.

  4. Set the key as the RAG_API_KEY environment variable in the terminal where you run Claude Code. Never put it in a file that might be committed.

    bash
    export RAG_API_KEY='paste-your-key-here'

    To keep it for new terminals, add that line to your shell profile, such as ~/.zshrc.

Make one key for each machine or agent, so you can revoke one without breaking the others. See Keys & attribution.

6. Connect Claude Code ​

  1. On API keys, find Connect your agent and select Copy. The configuration connects agents to the namespace selected in the switcher. It looks like this, with your namespace id in place of ws-…:

    json
    {
  "mcpServers": {
    "rag-corpus": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    },
    "rag-ledger": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    }
  }
}

  2. Save it as .mcp.json in the root of your project folder. The file holds no secret: Claude Code reads the key from RAG_API_KEY when it starts.

  3. In that folder, start Claude Code from the terminal where you set RAG_API_KEY. When Claude Code asks whether to use the project's MCP servers, approve rag-corpus and rag-ledger.

Agent instructions refer to the tools by the server names rag-corpus and rag-ledger. For your oldest namespace, the console already uses those names. For any other, the names end in its id, such as rag-corpus-ws-…. If this project uses only that namespace, rename them to rag-corpus and rag-ledger. See Server names.

The desktop app does not read your shell profile

macOS apps that you open from the Dock or Finder do not load your shell profile. In the Claude Code desktop app, ${RAG_API_KEY} can therefore expand to nothing, and every call fails with 401. Claude Code shows how to supply the key another way.

7. Run your first search ​

Ask Claude Code a question your source can answer, and ask it to cite what it found. For example, for code:

text
Use search_corpus to find where we handle failed card payments.
Cite the repository, file and lines for each result.

For documents:

text
Search our team handbook for the parental leave policy.
Quote the relevant passage and cite where it came from.

The agent calls search_corpus and answers with citations, for example payments-api/src/retry.ts:40-72. See Search & citations.

8. Record your first decision ​

Ask the agent to record a decision in the ledger. Give it a project name to file the topic under. The name can use letters, digits, dots, hyphens and underscores, and it becomes the start of the topic id. For example:

text
Record a decision in the Workstate ledger, under the project "rollout":
we connect our team handbook to Workstate first, and our code repositories
next month, because the support team needs the handbook now.
Then tell me the topic id.

The agent calls ledger_create, and the new topic gets an id such as rollout-0001. New decisions start as Proposed unless the agent sets another status. The topic is attributed to you and to the agent you used.

9. See it in the console ​

  1. Open Ledger. It lists every topic in the namespace, the most recently updated first, so your decision is at the top. To find a topic by meaning, type words from it (for example, "handbook first") and select Search. A new topic takes a few seconds to appear in search results.
  2. Open the topic. Its page shows the Current state, the Summary (fixed when the topic was opened) and the append-only History. The line under the title names you and the agent you used.

Check it worked ​

  • In Claude Code, the /mcp command lists rag-corpus and rag-ledger as connected.
  • The search answer cites repositories, files and line numbers from your source.
  • The topic page says "Opened by" followed by your email address.
  • On API keys, your key shows a Last used time.

Troubleshooting ​

What you seeLikely causeWhat to do
Every call fails with 401 (missing bearer token or invalid or revoked key)RAG_API_KEY is not set where the agent runs, so the key arrives empty. Or the key was revoked, or copied incompletely.Set RAG_API_KEY in that terminal and restart Claude Code. If the key is lost or revoked, create a new one.
no grant for namespaceThe X-RAG-Namespace header names a namespace you cannot reach, or can no longer reach.Select the right namespace in the switcher, and copy the configuration again from API keys.
principal has no workspace grantsYou cannot reach any namespace.If you are an owner or admin, create one on Namespaces. Otherwise, ask an owner or admin to give you one on the Team page.
Search returns nothing, or not what you expectThe first sync has not finished, or your source is in a different namespace from the one in your configuration.Check that the source says Up to date. Check that the namespace id in .mcp.json is the one your source belongs to.
repo not given when recordingThe agent did not give a project for the topic.Tell it which project to file the topic under.
The tools do not appear.mcp.json is not in the folder where you started Claude Code, or the servers were not approved.Start Claude Code in the project root, and approve the servers.

Next steps ​

Workstate is built by Nerdstorm Pty Ltd, Sydney.