Skip to main content

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.

​
General

Mains is currently available for macOS only. Windows and Linux support is planned.
Mains supports three agent runtimes: Claude Code (via the Anthropic CLI), GitHub Copilot (via the Copilot CLI), and OpenAI Codex (via the Codex app server). You can use any combination in your workspaces.
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.
All data is stored locally in a SQLite database at ~/Library/Application Support/mains/mains.db on macOS. See the Privacy page for details.

​
Workspaces

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.
Yes. Each workspace has its own Git worktree, so multiple agent sessions can run in parallel without file conflicts. See Multi Session.
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.

​
Connections

Mains supports GitHub, GitLab, Linear, Jira, Asana, Trello, Notion, and Sentry. Each connection syncs issues or tasks into Mains’s local entity store for use as agent context.
API tokens and OAuth credentials are stored encrypted in the local database. They never leave your machine.
The initial sync fetches existing data. Subsequent syncs are incremental and can be triggered manually or scheduled via automations. The minimum automation interval is one minute.

​
Troubleshooting

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.
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.
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.
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.
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.
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.
Go to Settings > Apps 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.
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.
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.
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.