FAQ

Short answers to common questions. Each answer links to the page with the details.

General

What is Workstate?

Workstate is the shared memory and decision record for people and their agents. It connects the knowledge your team already keeps, such as code, documents and tickets, and keeps a record of what the team decided and why. See What is Workstate?

Is Workstate an agent?

No. Workstate doesn't run agents or act on its own. It is the shared layer that the agents you already use search and write to, such as Claude Code, Cursor and Codex. See How Workstate works.

Which agents and clients work with Workstate?

Claude Code, Claude desktop, Cursor, Codex, any other client that supports MCP (Model Context Protocol), and agents you build yourself. See Agents & clients.

Do I need to be an engineer?

No. You can search and read the ledger in the console, and admins add sources through forms. Connecting an agent means pasting a configuration that the console writes for you. See the Quickstart.

What is the ledger?

The ledger is an append-only record of your team's decisions, incidents, defects and investigations. Agents search it before they act, and add to it when they finish. See The ledger.

What is a namespace?

A namespace is a separate index inside your account. Sources, search and the ledger each work inside one, and everyone with access to a namespace can see everything in it. See Namespaces.

How do I get an account?

Workstate is invite-only. Ask an Owner or Admin of your team's account to invite an email address that is verified on your GitHub account, and to give you the namespaces you need. Then sign in with GitHub. See Team & invites.

Sources

What can Workstate read today?

GitHub repositories, Confluence Cloud pages, Jira Cloud issues, and files you upload, including PDF, Word, Excel and PowerPoint files. See Sources.

Can it read Slack or Google Drive?

Not yet. Connectors for Slack, Google Drive and other tools are planned Coming soon. Until then, you can download documents as PDF or Word files and upload them. See Coming soon.

Does Workstate get access to all my repositories?

No. Signing in with GitHub grants no access to repositories. Workstate reads only the repositories you choose when you install the Workstate GitHub App, and it can only read them. See GitHub.

What does Workstate index from a repository?

The latest files on the default branch, without history, pull requests or issues. It skips hidden files, dependency and build folders, lockfiles, minified files, binary files, and files over 1 MB. See What Workstate indexes, and what it skips.

What happens when I stop sharing a repository with the GitHub App?

Workstate removes that repository from the index at the source's next sync. See GitHub.

How often do sources sync?

New GitHub, Confluence and Jira sources sync once a day by default. An Owner or Admin can choose anything from every 5 minutes to once a week, and anyone can select Sync now. Upload sources change only when someone uploads. See Sync schedules.

Why aren't my repository's Markdown files in the wiki corpus?

Every file from GitHub, Markdown included, is in the code corpus. The wiki corpus holds Confluence pages, Jira issues and uploaded documents. See Search & citations.

Agents & clients

How do I connect my agent?

Create a key on the API keys page, set it as RAG_API_KEY, and paste the configuration from Connect your agent into your client. See API keys.

Can I rename the servers?

Yes, as long as your agent instructions use the same names. The standard instructions refer to rag-corpus and rag-ledger, so an agent that uses one namespace should have its servers named that way, whichever namespace it is. An agent that uses several namespaces needs different names for each namespace's servers. See Server names.

Can one agent use several namespaces?

Yes. On the API keys page, copy the configuration for each namespace in turn, switching namespace in between, and combine them in one file. Each namespace's servers have their own names, and each server names its namespace in the X-RAG-Namespace header. See Connect an agent to several namespaces.

Where should I keep my API key?

In the RAG_API_KEY environment variable where your agent runs, or in the macOS Keychain with Claude Code's headersHelper. Never put it in a file that might be committed. See Store your key safely.

Will my agent use Workstate on its own?

Your agent sees the tools once it is connected, but it follows its instructions. Tell it to search before non-obvious decisions and to record the outcome when it finishes. See Agent instructions.

The ledger

Who can write to the ledger?

Anyone with access to a namespace, through their agent. The console's Ledger page is read-only. See Recording decisions.

Can I edit or delete a ledger entry?

No, the history is append-only. Append a correction, supersede a topic that turned out wrong, or archive noise to hide it from search. See Supersede, move & archive.

How is authorship recorded?

Every topic and entry records the person whose API key made the call, plus the agent's label. An agent can't write under someone else's name. See Keys & attribution.

What should we record in the ledger?

Whatever a future person or agent would regret not knowing: decisions and their reasons, root causes, workarounds and rejected options. Leave out trivia, secrets and personal details. See What's worth logging.

How soon can others find a new topic?

A new topic appears in the console's Ledger list, and can be fetched by its id, at once. Search finds it within a few seconds. See The ledger.

Security & data

Who can see what I index?

Everyone with access to the namespace you index it into. There are no per-document permissions, so put sensitive material in its own namespace. See Managing namespaces.

Are secrets filtered out?

Partly. Uploads refuse private keys and .env files, and GitHub sources skip hidden files such as .env. GitHub sources don't look inside files for secrets, so remove committed credentials before you connect a repository. See Security & privacy.

Can I delete my data?

Deleting a source removes its indexed content and files. Deleting a namespace removes everything in it, including its ledger topics. Archiving a ledger topic only hides it, and deleting an account is not built yet Coming soon. See Deleting data.

Does Workstate support single sign-on?

Not yet Coming soon. Everyone signs in with GitHub. See Security & privacy.

How do I report a security issue?

Email hello@workstate.io with what you found and how to reproduce it. See Report a security issue.

Troubleshooting

Why do I get 401?

Your API key is missing, empty, revoked or mistyped. On macOS, apps opened from the Dock don't read your shell profile, so ${RAG_API_KEY} is empty for them. See When a key stops working.

Why are my results empty?

Check that you are searching the namespace the content is in, and that the source's first sync has finished. Then widen your filters: repository names must match exactly, and GitHub Markdown is in the code corpus, not the wiki corpus. The file may also have been skipped, for example because it is hidden or over 1 MB. See Search & citations.

I was invited, but the console says "No namespace yet"

Nobody has given you a namespace yet. Ask an Owner or Admin of your account to tick one for you in the Namespaces column on the Team page. See Change who reaches a namespace.

Sign-in says "Workstate is invite-only for now"

No invitation matched a verified email address on the GitHub account you used. Ask an admin to invite an address that is verified on that GitHub account, then sign in again. See Team & invites.

My agent says "no grant for namespace"

The X-RAG-Namespace header names a namespace that your key has no access to, or one that was deleted. Copy the right id from the Namespaces page. See Managing namespaces.