> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mains.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ & Troubleshooting

> Common questions and known issues

## **General**

<AccordionGroup>
  <Accordion title="What platforms does Mains support?">
    Mains is currently available for **macOS** only. Windows and Linux support is planned.
  </Accordion>

  <Accordion title="Which AI agents are supported?">
    Mains supports four agent runtimes: **Claude Code** (via the Anthropic CLI), **GitHub Copilot** (via the Copilot CLI), **OpenAI Codex** (via the Codex app server), and **Cursor** (via the Cursor Agent CLI over ACP). You can use any combination in your workspaces -- the [space picker](/spaces) switches between them.
  </Accordion>

  <Accordion title="Do I need an API key?">
    For **Claude Code**, you need a Claude account authenticated via `claude /login`. For **GitHub Copilot**, you need an active Copilot subscription and GitHub CLI authentication (`gh auth status`). For **OpenAI Codex**, you need to authenticate via `codex auth login`. For **Cursor**, run the `agent` CLI once and sign in with your Cursor account.
  </Accordion>

  <Accordion title="Where is my data stored?">
    All data is stored locally in a SQLite database at `~/Library/Application Support/mains/mains.db` on macOS. See the [Privacy](/privacy) page for details.
  </Accordion>
</AccordionGroup>

## **Workspaces**

<AccordionGroup>
  <Accordion title="What happens when I create a workspace?">
    Mains creates an isolated Git worktree for the workspace. This gives the workspace its own working directory and branch while sharing Git history with the original repository.
  </Accordion>

  <Accordion title="Can I run multiple agents at the same time?">
    Yes. Each workspace has its own Git worktree, so multiple agent sessions can run in parallel without file conflicts. See [Multi Session](/multi-session).
  </Accordion>

  <Accordion title="What happens when I archive a workspace?">
    The workspace is hidden from the sidebar and its worktree is cleaned up to free disk space. The workspace data remains in the database and can be restored if needed.
  </Accordion>
</AccordionGroup>

## **Connections**

<AccordionGroup>
  <Accordion title="Which services can I connect?">
    Mains supports [GitHub](/github), [GitLab](/gitlab), [Linear](/linear), [Jira](/jira), [Asana](/asana), [Trello](/trello), and [Sentry](/sentry) for issues and tasks -- each syncs into Mains's local entity store for use as agent context. [Socket.dev](/dependency-guards) connects separately as the supply-chain guard provider.
  </Accordion>

  <Accordion title="How are my credentials stored?">
    API tokens and OAuth credentials are stored encrypted in the local database. They never leave your machine.
  </Accordion>

  <Accordion title="How often does data sync?">
    The initial sync fetches existing data. Subsequent syncs are incremental and can be triggered manually or scheduled via [automations](/automations). The minimum automation interval is one minute.
  </Accordion>
</AccordionGroup>

## **Troubleshooting**

<AccordionGroup>
  <Accordion title="Claude Code agent is not available">
    Make sure the Claude CLI is installed and authenticated. Run `claude /login` in your terminal to verify. Mains requires the Claude CLI binary to be accessible from your system PATH.
  </Accordion>

  <Accordion title="GitHub Copilot agent is not available">
    Verify your GitHub CLI authentication with `gh auth status` and ensure you have an active Copilot subscription. The Copilot CLI binary must be accessible from your system PATH.
  </Accordion>

  <Accordion title="OpenAI Codex agent is not available">
    Make sure the Codex CLI is installed and authenticated. Run `codex auth login` in your terminal. The Codex binary must be accessible from your system PATH.
  </Accordion>

  <Accordion title="Workspace worktree creation fails">
    This can happen if the repository already has a worktree at the target path, or if there are uncommitted changes in the source repo that conflict. Try running `git worktree list` in your terminal to check existing worktrees, and `git worktree prune` to clean up stale entries.
  </Accordion>

  <Accordion title="Agent run is stuck or unresponsive">
    You can abort a running session from the workspace UI. If the agent is waiting for tool approval, check for a pending approval dialog in the workspace. If the run remains stuck, try restarting the app -- active runs are tracked and can be recovered.
  </Accordion>

  <Accordion title="MCP server tools are not showing up">
    MCP servers must be registered before starting a session. Add servers via `claude mcp add` and verify with `claude mcp list`. Restart the workspace session after adding new servers.
  </Accordion>

  <Accordion title="Synced issues are not appearing">
    Go to **Settings > Connections** and verify your connection is active. Check that you've selected the correct repositories, teams, or projects to sync. Trigger a manual sync to refresh data.
  </Accordion>

  <Accordion title="Database reset">
    If you need to reset the local database, delete the file at `~/Library/Application Support/mains/mains.db` and restart Mains. This removes all local data including workspaces, runs, and connection credentials.
  </Accordion>

  <Accordion title="macOS security warning on first launch">
    macOS may block Mains since it's downloaded from the internet. Go to **System Settings > Privacy & Security** and click **Open Anyway**, or right-click the app and select **Open** to bypass the warning.
  </Accordion>

  <Accordion title="macOS Keychain prompt: &#x22;mains wants to use your confidential information&#x22;">
    On launch, macOS may show a dialog saying **mains wants to use your confidential information stored in "mains Safe Storage" in your keychain**. This is expected -- Mains uses Electron's `safeStorage` API to encrypt sensitive data like connection tokens and API keys. macOS requires your permission before an app can access its own Keychain entry.

    * Click **Allow** to grant access for this session
    * Click **Always Allow** to stop the prompt from appearing again
    * Clicking **Deny** will prevent Mains from reading encrypted credentials, which may cause connection features to fail

    This prompt typically appears once after installation or after a macOS update resets Keychain permissions.
  </Accordion>
</AccordionGroup>