Connect Claude Code
Connect Plenar to Claude Code so you can manage your schedule from the terminal. Two options: the CLI (recommended) handles everything automatically, or you can configure manually.
Prerequisites
- A Plenar project with at least one team member assigned
- Claude Code installed
- Your user assigned to the project (you need to be a team member for Plenar to schedule work for you)
Option A: CLI (recommended)
The Plenar CLI handles authentication, project selection, and configuration in one step.
1. Install the CLI
npm install -g @plenar/cli2. Run connect
plenar connectThis opens your browser to sign in, then walks you through:
- Authenticate — sign in via browser (OAuth)
- Select project — pick the project you are working on
- Configure MCP — writes
.mcp.jsonwith your token and the Plenar MCP endpoint - Update CLAUDE.md — adds the Plenar workflow instructions
- Set up hooks — adds agent coordination hooks to
.claude/settings.json. These ensure Plenar tracks which agent is working on each task, so your team can see who is doing what in the dashboard.
When it finishes, you see a summary with your project name, user, and connected repo.
3. Verify
Start a Claude Code session and say:
Show me my tasks in PlenarClaude calls plenar_get_my_tasks and displays your assigned tasks. If this works, you are connected.
Managing the connection
# Check connection status
plenar status
# Reconnect (switch user or project)
plenar connect
# Remove all Plenar config from this repo
plenar disconnectRunning plenar connect on an already-connected repo gives you three choices: keep the current connection, switch to a different user/project, or disconnect entirely.
Option B: Manual configuration
If you prefer to configure manually or cannot use the CLI.
1. Generate an API token
- Open your project in the Plenar dashboard
- Go to Settings > API Tokens
- Click Generate Token
- Name it (e.g., “Claude Code”) and choose a role:
- Planner — can preview and apply changes
- Contributor — can preview but not apply
- Copy the token immediately. It is shown only once.
2. Create .mcp.json
Create or edit .mcp.json in your project root:
{
"mcpServers": {
"plenar": {
"type": "sse",
"url": "https://dashboard.plenar.app/mcp",
"headers": {
"x-api-token": "YOUR_API_TOKEN_HERE"
}
}
}
}Replace YOUR_API_TOKEN_HERE with the token from step 1.
3. Verify
Start a Claude Code session and say:
Show me my tasks in PlenarAdd workflow instructions to CLAUDE.md
For the best experience, add Plenar workflow instructions to your project’s CLAUDE.md file. The CLI does this automatically, but if you configured manually, you can add them yourself.
Plenar can generate these instructions from the project settings page. The generated block includes guidance for:
- Starting tasks when you begin work
- Completing tasks when you finish
- Reporting blockers when you are stuck
- Linking PRs and artifacts
- Using the suggested branch naming convention
Minimal example:
## Plenar Workflow
When starting a task, ask: "Should I mark this as started in Plenar?"
If yes, the response includes a suggested_branch name for your git branch.
When finishing a task, ask: "Should I mark this as completed?"
The response includes the next suggested task to work on.
When creating a PR, ask: "Should I link this PR to the task in Plenar?"
When blocked, call plenar_report_blocker with a description.See Track Progress for the full recommended workflow.
Troubleshooting
”No tasks found”
Your user must be assigned as a team member on the project. Go to Settings > Team in the dashboard and verify your assignment. Being an organization member is not enough — you must be explicitly added to the project.
”Permission denied” on apply
Your API token has the Contributor role. Generate a new token with Planner role, or re-run plenar connect and select a project where you have planner access.
Connection timeout
Verify the URL is exactly https://dashboard.plenar.app/mcp and your network allows HTTPS connections.
Tools not appearing
Restart your Claude Code session after modifying .mcp.json. Claude loads MCP server configurations at startup.
CLI: “Existing connection is invalid”
Your token may have expired or been revoked. Run plenar connect again to re-authenticate.