@ismail-mirza/agent

MCP server for Claude Code that connects to the Periscale Orchestrator — manage sprint tickets, share team knowledge, run browser tests, and track agent sessions, all from inside Claude Code.

How it fits together

Claude Code (you)
    │
    │  MCP stdio
    ▼
@ismail-mirza/agent          ←── this package
    │
    │  WebSocket  wss://orchestrator.periscale.ai/ws
    ▼
Periscale Orchestrator UI    ←── Next.js dashboard + WS server
    │
    ├── Chrome Extension      ←── runs browser tests on your behalf
    └── PostgreSQL            ←── tickets, sessions, experiences

• Agent (@ismail-mirza/agent) — runs as a local MCP server inside Claude Code. Exposes tools for tickets, browser tests, skills, file system, shell commands, and team knowledge.
• Orchestrator UI — the central dashboard and WebSocket hub. All agents connect here. Hosts the sprint board, live session monitor, shared experiences, and browser test dispatcher.
• Chrome Extension — connects to the same WebSocket server. Receives run_browser_test commands from any agent and executes them in the active browser tab, streaming results back.

Quick start

1. Install and authenticate

# Option A — browser OAuth (recommended)
npx @ismail-mirza/agent init

# Option B — email/password
npx @ismail-mirza/agent login --email [email protected] --password secret

# Option C — paste a token directly
npx @ismail-mirza/agent config --token psc_your_token_here

init opens a browser tab to the Orchestrator UI login page. After you log in, the token is saved automatically to ~/.periscale/config.json.

2. Point to your orchestrator (if self-hosted)

npx @ismail-mirza/agent config \
  --url wss://your-orchestrator.example.com/ws \
  --project my-project \
  --name alice

Cloud default: wss://orchestrator.periscale.ai/ws

3. Add to Claude Code

// ~/.claude/mcp.json
{
  "mcpServers": {
    "periscale": {
      "command": "npx",
      "args": ["-y", "@ismail-mirza/agent"]
    }
  }
}

Restart Claude Code — the tools are now available.

Setting up the Orchestrator UI

Local development

git clone <orchestrator-ui-repo>
cd orchestrator-ui

cp .env.example .env.local
# Edit .env.local:
#   DATABASE_URL=postgresql://user:pass@localhost:5432/periscale
#   NEXT_PUBLIC_APP_URL=http://localhost:3000

npm install
npm run dev   # starts Next.js + WebSocket server on :3000

Visit http://localhost:3000 — you'll be redirected to /register to create the first admin account.

Then update your agent config to point to the local server:

npx @ismail-mirza/agent config --url ws://localhost:3000/ws --project my-project

Creating an agent token manually

1. Log in to the Orchestrator UI
2. Open a project → click Tokens
3. Create a token with type agent
4. Copy the psc_… token and run:

npx @ismail-mirza/agent config --token psc_your_token_here

Setting up the Chrome Extension

The extension connects to the same WebSocket server and executes browser tests dispatched by agents.

Install

Load the extension as an unpacked extension from packages/extension/dist/:

1. Go to chrome://extensions
2. Enable Developer mode
3. Click Load unpacked → select packages/extension/dist/

Configure

Via extension popup

Open the extension popup and set:

• Server URL: ws://localhost:3000/ws (local) or wss://orchestrator.periscale.ai/ws (cloud)
• Token: An extension type token from the Orchestrator UI

Via browser console

localStorage.setItem('serverUrl', 'ws://localhost:3000/ws');
localStorage.setItem('authToken', 'psc_your_extension_token');

Verify connection

Open DevTools → Network → WS filter. You should see a connection to /ws with status 101 Switching Protocols.

Create an extension token

Same as agent tokens but select type extension:

1. Orchestrator UI → project → Tokens → Create token
2. Type: Browser Extension
3. Copy and paste into the extension popup

Available MCP tools

Browser tests

| Tool | Description | |------|-------------| | run_browser_test | Dispatch an AI-driven browser test to the connected Chrome extension | | get_test_status | Poll a test run for status and results | | stop_test | Cancel a running test | | take_screenshot | Capture a PNG screenshot of the active tab | | record_video | Record a WebM video of the active tab |

Tickets

| Tool | Description | |------|-------------| | list_tickets | List sprint tickets (defaults to your assigned tickets) | | create_ticket | Create a new ticket on the shared sprint board | | update_ticket | Update ticket status, assignee, plan, test results, etc. | | sync_tickets | Sync between local .claude/tickets/ files and the database |

Team knowledge

| Tool | Description | |------|-------------| | search_experiences | Search lessons learned recorded by all developers on the project | | record_experience | Save a lesson learned after solving a non-obvious problem | | upvote_experience | Upvote a helpful experience to surface it to others |

Sessions

| Tool | Description | |------|-------------| | report_progress | Report what this session is doing (visible on the dashboard in real time) | | list_sessions | List other active Claude Code sessions on the same project |

Local tools

| Tool | Description | |------|-------------| | read_file | Read a local file | | write_file | Write a local file | | list_directory | List files in a directory | | run_command | Execute a shell command | | install_skill | Install a Claude Code slash command skill | | list_skills | List installed skills | | read_skill | Read the content of a skill |

Config reference

Config is stored at ~/.periscale/config.json.

npx @ismail-mirza/agent config --token <TOKEN>           # set auth token
npx @ismail-mirza/agent config --url <WSS_URL>           # orchestrator WebSocket URL
npx @ismail-mirza/agent config --project <SLUG>          # project slug
npx @ismail-mirza/agent config --name <DEVELOPER_NAME>   # your name (shown in dashboard)
npx @ismail-mirza/agent config --local-path <PATH>       # local project root

| Key | Default | Description | |-----|---------|-------------| | token | — | psc_ agent token (required) | | orchestratorUrl | wss://orchestrator.periscale.ai/ws | WebSocket server URL | | project | current directory name | Project slug | | agentName | — | Your developer name — used for ticket assignment filtering | | localPath | — | Local project root path |

Requirements

• Node.js 18+
• Periscale Orchestrator UI running (local or cloud)
• Chrome extension installed and connected (for browser test tools)