Set up your first agent
From a fresh install to a working AI agent. The two parts most beginners miss are at the top: how AgentsRoom relates to the AI CLIs, and how to sign in.
How AgentsRoom works (read this first)
AgentsRoom is the cockpit. The AI CLIs (Claude Code, Codex, OpenCode, Gemini, Aider) are the engines. You sign in to the engines once via their own command, then AgentsRoom drives them visually. AgentsRoom never stores or sees your tokens, API keys or ChatGPT password: those stay inside each CLI's own secure storage on your machine.
There is no "Log in to ChatGPT" or "Log in to Anthropic" button inside AgentsRoom by design. The login lives in the CLI you install in step 0 below.
Before you start
- ✓macOS 14+ (Sonoma or later)
- ✓At least one AI coding CLI installed (Claude, Codex, OpenCode, Gemini CLI or Aider)
e.g. npm install -g @anthropic-ai/claude-code - ✓An active subscription or API key for your chosen provider
Step 0: install and sign in to your AI engine
Pick one provider to start (you can add more later). For each one: install the CLI, run it once to sign in, verify it works. Then jump to step 1.
Click a provider to expand its setup steps.
Claude (Anthropic)Recommended for first-time users
Works with
Claude Pro, Claude Max, or an Anthropic API key.
1. Install
npm install -g @anthropic-ai/claude-code2. Sign in
Run claude once in any terminal. A browser window opens for sign-in with your Anthropic account.
3. Verify
Run the install command above, then run the CLI's name alone in your terminal (e.g. type "claude" and press enter). You should see a welcome prompt. Type "hello" and press enter: if you get an answer, you're ready to use it inside AgentsRoom.
Codex (OpenAI / ChatGPT)Use your ChatGPT account
Works with
ChatGPT Plus, Pro, Team or Enterprise, or an OpenAI API key.
1. Install
npm install -g @openai/codex2. Sign in
Run codex once in any terminal. A browser window opens. Sign in with your ChatGPT account, the same one you use on chatgpt.com.
3. Verify
Run the install command above, then run the CLI's name alone in your terminal (e.g. type "claude" and press enter). You should see a welcome prompt. Type "hello" and press enter: if you get an answer, you're ready to use it inside AgentsRoom.
OpenCodeBring your own provider
Works with
Any provider you configure: Anthropic, OpenAI, OpenRouter, and more.
1. Install
npm install -g opencode-ai2. Sign in
Run opencode auth login and follow the prompts to add a provider key.
3. Verify
Run the install command above, then run the CLI's name alone in your terminal (e.g. type "claude" and press enter). You should see a welcome prompt. Type "hello" and press enter: if you get an answer, you're ready to use it inside AgentsRoom.
Gemini CLI (Google)Free tier available
Works with
A Google account (free tier available) or a Gemini API key.
1. Install
npm install -g @google/gemini-cli2. Sign in
Run gemini once. A browser window opens for Google sign-in.
3. Verify
Run the install command above, then run the CLI's name alone in your terminal (e.g. type "claude" and press enter). You should see a welcome prompt. Type "hello" and press enter: if you get an answer, you're ready to use it inside AgentsRoom.
AiderPower users
Works with
Any provider via API key (Anthropic, OpenAI, DeepSeek and more).
1. Install
pip install aider-chat2. Sign in
No login command. Set your API key as an environment variable in your shell profile, for example: export ANTHROPIC_API_KEY=sk-...
3. Verify
Run the install command above, then run the CLI's name alone in your terminal (e.g. type "claude" and press enter). You should see a welcome prompt. Type "hello" and press enter: if you get an answer, you're ready to use it inside AgentsRoom.
Stuck at this step? See the troubleshooting section at the bottom of this page.
Download and install AgentsRoom
Download the .dmg file, open it, and drag AgentsRoom to your Applications folder. Launch it from Spotlight or the Applications folder.
Tip: AgentsRoom auto-checks for updates. You'll be notified when a new version is available.
Create your first project
Click the + button in the sidebar. Select any folder on your machine. This is where your AI agents will work. Name your project and assign it to a zone.
Tip: Each project maps to a real folder. Agents run the CLI of your chosen provider in that directory, just like you would in your terminal.
Add your first agent
Inside your project, click Add Agent. Pick a role (Fullstack is a good start), then a provider (the engine you set up in step 0), then a model (Sonnet is recommended for Claude). Optionally write an initial prompt and click Launch. The terminal opens and runs the CLI for you.
Tip: If the terminal looks empty or shows a login screen, the CLI from step 0 is not signed in yet. Open a regular terminal, run claude or codex (or your provider's command) once, complete the sign-in, then come back.
Watch it work
The terminal shows live output: every file read, every edit. Status changes: thinking, coding, done. You get a macOS notification when it finishes.
Tip: You can launch multiple agents at once. Each gets its own terminal and works independently.
Customize your setup
Edit CLAUDE.md directly from AgentsRoom to give agents better context. Change models, adjust permissions, configure hooks. Add more agents with different roles or providers.
Tip: Opus for architecture. Sonnet for dev. Haiku for quick tasks like tests.
Tips and tricks
1.Use Opus for architecture decisions, Sonnet for daily coding, Haiku for quick tasks
2.Group projects by zone (Work, Personal, Side-projects) for better organization
3.Edit CLAUDE.md from AgentsRoom to give agents better project context
4.Enable macOS notifications so you can multitask while agents work
5.Start with one agent per project, add more as you get comfortable
Troubleshooting
My agent terminal looks empty or stuck
Most of the time the CLI is not signed in. Open a regular terminal (Terminal.app), run the CLI's command alone (claude, codex, gemini, opencode), complete the browser sign-in, then go back to AgentsRoom and launch the agent again. AgentsRoom does not have its own login screen: the auth lives in the CLI.
command not found: claude (or codex, gemini, etc.)
The CLI is not installed, or your shell PATH does not see it. Re-run the install command from step 0 above. If you use nvm, install the CLI with the same Node version you use day-to-day, otherwise the binary will not be in PATH when AgentsRoom launches.
I don't see a button to log in to ChatGPT or Claude inside AgentsRoom
By design. AgentsRoom is a UI on top of CLIs and never handles your credentials directly. The sign-in is done once inside the CLI (run claude or codex in a terminal), then AgentsRoom uses that session. This is what makes AgentsRoom safer than tools that intercept your tokens.
Agent stuck on "thinking"
Check that your subscription or API key is active for the selected provider. Try running the CLI directly in your terminal to see the real error message: Claude or OpenAI sometimes throttle or expire sessions silently.
No projects showing in the sidebar
Make sure you selected a valid folder when creating the project. The folder must exist on disk. Restart AgentsRoom if a project was added but not yet visible.
I installed the CLI but AgentsRoom still says "command not found"
AgentsRoom inherits its PATH from your login shell, not from your interactive terminal. Quit AgentsRoom completely, open a new terminal, verify the CLI is callable from a fresh shell session (which claude), then re-launch AgentsRoom.
Next steps
Ready to start?
Download AgentsRoom and launch your first agent in 30 seconds.
Companion app: monitor your agents on the go
Bring your own: Claude, Codex, Gemini CLI, or other AI provider.
Push bugs and requests straight to your public backlog.