# Set up Shuriken in your first hour

> Set up Shuriken in order: sign in, add a project, add your accounts and keys, choose when chats switch, add MCP servers once, then your phone and servers.

Source: https://shuriken.sh/guides/set-up-shuriken

Set up Shuriken in order: sign in, add a project, add your accounts and keys, choose when chats switch, add MCP servers once, then your phone and servers.

By Shuriken Updated 27 October 2026 5 min read

**Contents**

To set up Shuriken, sign in, add a project, then open Settings › Sources and add each account and key your agents should use. Check the switch settings on that page, add MCP servers once, and link your phone and servers last. The first three steps take about ten minutes. Not installed yet? [How to install Shuriken](https://shuriken.sh/guides/install-shuriken) has the download for each system.

## 1. Sign in #

Shuriken opens on its sign-in screen. Use Continue with Google, Continue with Apple, or your email; with email you can take a 6-digit code instead of a password. The account is free to start, with no card: a new account gets 14 days of Pro, then moves to the Free plan, which covers two sources and two linked devices. A browser doesn't count as a device. The [docs](https://shuriken.sh/docs) show each screen if one looks different.

## 2. Add a project #

Press Add project. It offers four ways in: Find a folder, Browse, New folder and Clone from GitHub. Clone from GitHub searches the repositories your GitHub account can see. That search needs the GitHub CLI (gh) on the device and GitHub signed in under Settings › Account; without them, type owner/repo or paste the link.

Coming from Claude Code or Codex in a terminal? Add project › Import from… lists the projects it finds on the device, with their past chats, and Import all brings them in. Sign-ins don't come across.

A project starts with its Main chat, which works on your own branch for quick changes. Each new chat gets its own git worktree and branch, so two agents never edit the same copy of a file.

## 3. Add your sources #

A source is an account sign-in or an API key: your Claude subscription, a second Claude account, the ChatGPT sign-in Codex uses, an API key. [What is a source](https://shuriken.sh/blog/what-is-a-source) explains why we picked the word.

- Open Settings › Sources and press Add source.
- Pick the agent. A subscription row reads "Sign in with your Claude account"; press Start sign-in and approve it in your browser, and it finishes by itself.
- For a key, choose API key ("billed per token"). For a local model or a compatible server, choose Custom endpoint and give its address (Ollama and LM Studio on the same computer are found for you).
- Repeat for every account you own and want to use.

When an agent is already signed in on the computer, the sheet shows Add current to take that sign-in as a source. Each source's row then shows its limit bars, such as the 5-hour and weekly ones. Use only accounts you own and are entitled to use; providers' terms may not allow sharing a subscription sign-in.

## 4. Check when chats switch #

With two sources for one agent, Shuriken moves your chats from the one in use to the other as it nears its limit. We call it hot swapping. The settings sit under Switch settings on the Sources page, and these are the defaults:

| Setting | Default | What it means |
| --- | --- | --- |
| Switch at | 99% | When a chat leaves a source. Anywhere from 50% to 100% |
| How | When one runs out | Stay on one source until it reaches the bar, then the next. Spread the work instead moves chats to the source with the most left, every 15 minutes by default |
| Start unused session limits | On | Starts an idle subscription's 5-hour window with one tiny background request, once per window. Never shows in a chat |
| Switch to API keys | Off | Turn on and API keys take chats only once every subscription of that agent is out. You can add several keys |
| Spend cap per fallback | $25 | Stops one fallback run's API spend at $25 |

The app's hint under Switch at says it plainly: "A source counts as low once its 5-hour or weekly limit reaches this." A Claude Code chat moves on its next request, subagents included. Codex and the other agents move when their turn ends. Every switch leaves a card in the chat saying which source took over and why.

Shuriken keeps one MCP list for all your agents, and an MCP sign-in follows you to every account and computer.

[Download](https://shuriken.sh/download)

## 5. Add MCP servers once #

Open Settings › Extensions › MCP servers. There are 57 ready-made connectors (GitHub, Linear, Sentry, Figma and 53 more), and any other server goes in by its address or command. Sign in to each one once, in your browser.

A server's ⋯ menu has Also add to… for other projects, and the sign-in carries over. We tied the sign-in to the server rather than to your AI account, because a switch to another Claude account would otherwise ask you to sign in again. Claude Code and Codex chats in the same project see the same servers.

## 6. Your phone and your servers #

The phone gets the web app: app.shuriken.sh in its browser, signed in to the same account. On an iPhone, Safari's Share › Add to Home Screen puts it next to your other apps. It has every chat, the queue and Changes. Native iPhone and Android apps are planned for November 2026.

A second computer only needs Shuriken installed and the same sign-in; it shows up in Settings › Devices as a linked device.

A server has no app. In Settings › Devices › Add device, choose A server and its system (Linux, macOS or Windows), then copy the one command shown:

- On Linux or macOS, run it in a terminal or over SSH. It uses sudo, so the password is asked once.
- On Windows, run it in PowerShell opened with Run as administrator.
- Run it within the hour; after that the command stops working. Until it finishes, the server is listed as "New server · Pending".

The command installs Shuriken as a service that starts at boot (on Linux and macOS it also updates itself). Running it again repairs the install.

## Two settings for long runs #

Keep awake has two settings per device: While working and Always. A computer signed in to Shuriken starts on Always, so it stays reachable; the screen can still turn off. While working, in the app's words, "never sleeps while anything runs".

Closing a MacBook's lid still sends it to sleep, whatever Keep awake says. Cocaine mode, the syringe button in the top bar, is for that: it keeps the laptop running with the lid shut. On a Mac it asks once for an administrator password. On Windows and Linux it depends on the machine, and the picker says what yours can do.

Then start a chat. The reasoning behind the switch defaults is in [how switching picks the next account](https://shuriken.sh/blog/how-switching-picks-the-next-account).

Share

[X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fset-up-shuriken&text=Set%20up%20Shuriken%20in%20your%20first%20hour)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fset-up-shuriken)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fset-up-shuriken&t=Set%20up%20Shuriken%20in%20your%20first%20hour)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fset-up-shuriken&title=Set%20up%20Shuriken%20in%20your%20first%20hour)[E-mail](mailto:?subject=Set%20up%20Shuriken%20in%20your%20first%20hour&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fset-up-shuriken)

## Frequently asked questions

**What should I set up first in Shuriken?**

A project and your sources. A source is an account sign-in or API key your agents use. With two sources for the same agent, Shuriken can move chats between them near a limit.

**When does Shuriken switch accounts?**

At 99% of a window by default. You can set anything from 50% to 100%, and choose When one runs out (stay on one source until it reaches the bar) or Spread the work (move chats to the source with the most left on a clock).

**Does Shuriken import my Claude Code projects?**

Yes. Add project › Import from… brings your projects and their past chats in from Claude Code or Codex. Sign-ins aren't imported; a sign-in already on the computer is offered in Sources instead.

**Are API keys used automatically?**

Not by default. Switch to API keys is off until you turn it on; then keys take chats only once every subscription of that agent is out, with a $25 spend cap per fallback run by default.

**How do I follow my chats on my phone?**

Open the web app in your phone's browser and sign in. In Safari, Share › Add to Home Screen installs it. Native iPhone and Android apps are planned for November 2026.

Global MCPs

One MCP list for every agent.

Add an MCP server once, choose its projects and sign in once. Your Claude Code, Codex and Gemini CLI chats all get it.

[Download](https://shuriken.sh/download)

[Other platforms](https://shuriken.sh/download#main)

## Keep reading

- [Shuriken vs Orca (2026): Comparison 27 Oct 2026 5 min read Orca is a free, MIT-licensed agent IDE with one-click account swaps. Shuriken moves your running chats to another account by itself when one runs out.](https://shuriken.sh/compare/orca)
- [Shuriken vs Agentastic (2026): Comparison 27 Oct 2026 7 min read Agentastic is a free Mac multi-agent IDE with Design Mode and cloud targets. Shuriken runs on Mac, Windows and Linux and moves chats between your accounts.](https://shuriken.sh/compare/agentastic)
- [Claude Code MCP server failed to connect: how to fix it: Guide 27 Oct 2026 6 min read Claude Code says Failed to connect when an MCP server never starts or answers. claude mcp get prints the error; a relative path is a frequent cause.](https://shuriken.sh/guides/claude-code-mcp-server-failed-to-connect)
- [Claude Code MCP server timeout: the settings that fix it: Guide 27 Oct 2026 4 min read Claude Code MCP server timeout errors: the startup timeout for slow servers, a per-server limit for long tool calls, the idle window, and big output.](https://shuriken.sh/guides/claude-code-mcp-timeout)
- [Claude Code across many projects: keep them apart: Guide 27 Oct 2026 6 min read Claude Code ties sessions, CLAUDE.md, settings and MCP servers to the folder you start it in. Run one session per project; put shared setup in user scope.](https://shuriken.sh/guides/claude-code-multiple-projects)
- [Claude Code skills vs subagents vs MCP: which one to use: Guide 27 Oct 2026 6 min read Claude Code skills vs subagents: a skill is know-how in your chat, a subagent is work in its own context, MCP is a live outside system. One table to pick.](https://shuriken.sh/guides/claude-code-skills-vs-subagents)
- [How to add an MCP server to Codex CLI: Guide 27 Oct 2026 4 min read Add an MCP server to Codex CLI with codex mcp add and the server's command, or write its table in config.toml. OAuth servers sign in with codex mcp login.](https://shuriken.sh/guides/codex-cli-mcp-servers)
- [Codex MCP server failed to start or timed out: fixes: Guide 27 Oct 2026 6 min read In Codex, "MCP client failed to start" means the command or handshake broke; "timed out after N seconds" means a slow server: raise its startup timeout.](https://shuriken.sh/guides/codex-mcp-server-failed-to-start)

## Free tools

- [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude)
- [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)