How to Use Claude Code with Ivern: A Step-by-Step Tutorial

How to Use Claude Code with Ivern: A Step-by-Step Tutorial

Claude Code has changed the game for developers. It's a powerful command-line AI assistant that can write, debug, and refactor code right in your terminal. For a full introduction, see our how to use Claude Code beginner guide. But it's a solo act.

What if you could connect Claude Code to a larger team of AI agents? A team with a Researcher to find documentation, a Tester to write unit tests, and a Reviewer to check for security flaws?

With Ivern, you can. Ivern is designed to coordinate the AI tools you already use, including powerful CLI agents like Claude Code. This is part of our "Bring Your Own Agent" (BYOA) philosophy. For more on combining Claude Code with other agents, see our guide on how to combine Claude Code with other AI agents.

This tutorial will walk you through the exact steps to connect your Claude Code assistant to an Ivern squad, turning your solo coder into a team player.

Related guides: Claude Code vs Cursor Comparison · Claude Code Task Management · 10 AI Agent Workflow Examples

Why Connect Claude Code to Ivern?

By default, Claude Code is a one-on-one conversational partner. It's brilliant, but it has limitations:

• No Task Management: You can't assign it a task and track its progress.
• No Team Collaboration: It can't hand off its work to another agent (like a tester or reviewer).
• No Parallel Work: It can only work on one thing at a time.

Connecting it to Ivern solves these problems. You get:

• A Task Board for Your Agent: Assign tasks to Claude Code in Ivern and track them on a kanban board.
• Multi-Agent Squads: Combine Claude Code with other agents (e.g., an OpenAI-powered Researcher and a Claude 3.5-powered Reviewer) in a single workflow.
• Automated Handoffs: Have Claude Code write a script, then automatically pass it to a Tester agent to generate unit tests.
• Centralized Visibility: See the real-time output of Claude Code and all your other agents in one unified dashboard.

What You'll Need

1. Claude Code: You should have it installed and working in your terminal.
2. Ivern Account: A free account from ivern.ai/signup.
3. The Ivern Agent: A small, open-source agent that runs locally to connect Claude Code to the Ivern platform.

This tutorial assumes you already have Claude Code running.

---

Step 1: Create a "BYOA" Connection in Ivern (2 minutes)

First, you need to tell Ivern to expect a connection from an external agent.

1. Log in to your Ivern account.
2. Go to Settings > Connections.
3. Click on the External Agents tab.
4. Click Connect New External Agent.
5. Give your agent a name, for example, "My Claude Code CLI".
6. You'll be presented with two values: an Agent ID and a Platform API Key.

Keep this window open. You'll need these two values in the next step.

Step 2: Install and Configure the Ivern Agent (3 minutes)

On your local machine (where you run Claude Code), you need to install the Ivern Agent. This is a lightweight, open-source process that listens for tasks from Ivern and passes them to Claude Code.

Installation

Open your terminal and run the following command to install the Ivern Agent CLI:

npm install -g @ivern/ivern-agent

This will install the ivern-agent command globally on your system.

Configuration

Now, configure the agent to connect to your Ivern account and your local Claude Code instance.

Run the setup command:

ivern-agent setup

This will prompt you for four pieces of information:

1. agentId: Copy this from the Ivern connections page you have open.
2. apiKey: This is the "Platform API Key" from the same page.
3. agentName: This is a local name, e.g., claude-code.
4. executionCommand: This is the crucial part. It's the command the Ivern agent will use to run a prompt with Claude Code. The command should include the {{prompt}} placeholder.

For Claude Code, the command is typically:

claude-code -p "{{prompt}}"

After you enter the information, the CLI will create a config.json file in your home directory at ~/.config/ivern-agent/config.json.

Your configuration file will look like this:

{
  "agentId": "cl_xxxxxxxxxxxxxxxxx",
  "apiKey": "iap_xxxxxxxxxxxxxxxxx",
  "agentName": "claude-code",
  "executionCommand": "claude-code -p "{{prompt}}""
}

Step 3: Run the Ivern Agent Locally

Your bridge is now configured. To open the connection, simply run:

ivern-agent start

You should see output confirming the agent is running and listening for tasks:

[Ivern Agent] Starting agent 'claude-code' (ID: cl_xxxxxxxx)...
[Ivern Agent] Polling for tasks from Ivern platform.
[Ivern Agent] Agent is ready. Waiting for tasks...

Leave this terminal window running. This process maintains the connection between Ivern's cloud platform and your local Claude Code instance.

Step 4: Add Your Claude Code Agent to a Squad

Now that your agent is connected, it will appear in Ivern as a usable agent, just like any cloud-based AI model.

1. Go back to the Ivern dashboard.
2. Click Create Squad (or edit an existing one).
3. Click Add Agent.
4. You will now see "My Claude Code CLI" (or whatever you named it) in the list of available agents. Select it.
5. Give it a role within the squad, for example, "Lead Developer".

Let's create a simple Code Generation squad:

• Agent 1: Lead Developer (Your Claude Code instance)
• Agent 2: Code Reviewer (Using the "Code Reviewer" template, which might use Claude 3.5 Sonnet or GPT-4o for a second opinion).

Click Create Squad.

Step 5: Assign a Task to Claude Code from Ivern

Now you can assign a task to your squad, and the work will be routed to your local Claude Code agent.

Go to your new squad's task board and create a new task:

Task Title: Write a Python script to fetch weather data.

Prompt: "Using Python, write a script that takes a city name as a command-line argument and uses the OpenWeatherMap API to print the current temperature. Include error handling for invalid city names."

When you assign this task, you'll see the following happen:

1. The Ivern platform sends the task to your locally running ivern-agent.
2. In your terminal, the ivern-agent will show that it received the task and is executing the command.
3. Claude Code will run locally with the prompt.
4. The output (the Python code) will be streamed from your local machine back to the Ivern task board in real-time.
5. Once Claude Code finishes, the task will be automatically handed off to the "Code Reviewer" agent in your squad.
6. The Code Reviewer will provide feedback on the generated code, right in the same task view.

You have successfully integrated your local CLI tool into a cloud-based, multi-agent workflow!

Common Questions & Troubleshooting

• Is my API key safe? Your Claude Code API key never leaves your machine. The Ivern Agent CLI interacts with Claude Code locally. The only key you provide to Ivern is the Platform API Key, which is just for authenticating your local agent with the Ivern platform.

• Does the agent need to run all the time? The ivern-agent start process only needs to be running when you want Ivern to be able to send tasks to Claude Code. If it's not running, tasks assigned to that agent will queue up in Ivern until the agent comes online.

• Can I connect other CLI tools? Yes. This BYOA (Bring Your Own Agent) approach works for any CLI tool that can accept a prompt as an argument. Just change the executionCommand in the config.json file. For example, you could connect a local script, another AI model, or any other command-line application.

• command not found: claude-code: This error means the ivern-agent can't find your claude-code executable. Make sure it's in your system's PATH. You can also provide the full path in the executionCommand, e.g., /usr/local/bin/claude-code -p "{{prompt}}".

Next Steps

Now that you have Claude Code integrated, you can build much more advanced workflows:

• Test-Driven Development Squad: Create a squad with a "Planner" that writes a spec, your "Claude Code" agent that writes the code, and a "Tester" that writes pytest unit tests for the code.
• Refactoring Squad: Use a "Code Analyst" to identify code smells in a codebase and then assign refactoring tasks to your Claude Code agent.
• Documentation Squad: Have an agent read a piece of code and generate documentation requirements, then assign your Claude Code agent to write the docstrings and README.

By connecting your favorite local tools to a central coordination hub like Ivern, you get the best of both worlds: the power and familiarity of your CLI, and the collaboration and task management of a multi-agent platform. For more agent integrations, see our OpenCode Complete Guide and Cursor integration guide.

Start building your connected squads for free →