Agentum

Control AI coding agents from your phone. Mirror Claude Code, GitHub Copilot, and OpenAI Codex to mobile - code from your couch, bed, or anywhere.

How It Works

┌──────────────┐     WebSocket      ┌──────────────┐
│  Your Phone  │ ◄────────────────► │   Desktop    │
│  (Agentum    │                    │(agentum start)│
│   Mobile)    │                    │              │
└──────────────┘                    └──────────────┘
                                           │
                                    ┌──────┴──────┐
                                    │ AI Agents   │
                                    │ Claude Code │
                                    │ Copilot     │
                                    │ Codex       │
                                    └─────────────┘

Prerequisites

You need Node.js (v18+) installed. Then, install and authenticate the AI agents you want to control:

| Agent | Install | Login | |-------|---------|-------| | Claude Code | npm install -g @anthropic-ai/claude-code | claude (follow prompts) | | GitHub Copilot | gh extension install github/gh-copilot | gh auth login | | OpenAI Codex | npm install -g @openai/codex | codex (follow prompts) |

Only install and authenticate the agents you plan to use.

Quick Setup

1. Install CLI on your desktop

npm install -g agentum

2. Start the server

npx agentum start

This shows your connection info:

Terminal server started on port 11042
Connect from mobile using IP: <your-ip>, Port: 11042

3. Find your IP (if needed)

# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Or just use
hostname -I   # Linux
ipconfig      # Windows

4. Get the mobile app

| Platform | Status | |----------|--------| | iOS | iOS link | | Android | Coming soon |

5. Connect

Open the mobile app and enter:

• IP/Host: Your desktop's IP address
• Port: 11042 (default)

That's it! Your AI agents now stream to your phone.

Commands

agentum start

Start the server. Run this first.

agentum start                    # Default: port 11042
agentum start --port 8080        # Custom port
agentum start --no-vnc           # Disable screen sharing

agentum run <command>

Run any command and mirror output to mobile.

agentum run "npm test"
agentum run "python train.py" -d     # Detached (background)
agentum run "make build" -n build    # Named session

agentum list

Show active sessions.

agentum attach <id>

Attach to a session locally. Press Ctrl+] to detach.

agentum kill <id>

Stop a session.

agentum screenshot

Capture screen to disk.

agentum screenshot                # Saves to /tmp
agentum screenshot -o ./shots     # Custom directory

agentum notify

Push notification to phone.

agentum notify -t "Done" -b "Build complete"
agentum notify -t "Error" -b "Tests failed" -P high

Remote Access (Tailscale) - Highly Recommended

Access from anywhere, not just your local network. Works through firewalls and NATs.

Setup

1. Install Tailscale on desktop and phone
2. Sign in with same account on both
3. Start Tailscale:

   tailscale up

4. Connect from mobile:
   • IP/Host: Your Tailscale IP (tailscale ip -4) or MagicDNS hostname (e.g., your-desktop-name)
   • Port: 11042

Ports

| Port | Service | Description | |-------|-----------|--------------------------| | 11042 | WebSocket | Mobile ↔ Desktop | | 11043 | VNC | Screen sharing (optional)|

Troubleshooting

Port in use?

agentum start --port 8080

Can't connect from phone?

• Same WiFi network?
• Firewall blocking port 11042?
• Try: ping <desktop-ip> from phone

Find your IP:

ifconfig | grep "inet "

Links

• Repository
• AirCodum