AI coding agent runtime — drive Claude Code, Gemini CLI, and Codex CLI from your phone or browser. Code stays on your machine; the agent runs locally.

codewithphone is the local agent runtime for CodeWithPhone. It connects your machine to the CodeWithPhone platform so you can run AI coding tasks using Claude Code, Gemini CLI, and Codex CLI directly on your local environment — supervised from your phone, browser, or wherever you are.

codewithphone runs on your machine and acts as a bridge between the CodeWithPhone platform and local AI CLI tools:

1. You create a coding session on codewithphone.com (or the mobile app)
2. The agent picks up tasks and executes them using installed AI runtimes (Claude Code, Gemini CLI, Codex CLI)
3. Code changes happen on your machine, in your real project directories
4. You review and approve changes through the web interface

CodeWithPhone App/Web  <───>  codewithphone.com  <───>  codewithphone (your machine)
                                                              │
                                                    ┌─────────┼─────────┐
                                                    ▼         ▼         ▼
                                                 Claude    Gemini    Codex
                                                  Code      CLI       CLI

One command (GitHub Release):

curl -fsSL https://raw.githubusercontent.com/shotforward/codewithphone/main/install.sh | bash

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/shotforward/codewithphone/main/install.sh | bash -s -- v0.2.0

From source (requires Go 1.25+):

git clone https://github.com/shotforward/codewithphone.git
cd codewithphone
go build -o codewithphone ./cmd/codewithphone
sudo mv codewithphone /usr/local/bin/

You only need one. codewithphone will auto-detect all installed runtimes.

codewithphone start

On first run, a PIN code will be displayed:

  ┌────────────────────────────────────────────────────────┐
  │  CodeWithPhone Authorization Required                  │
  │                                                        │
  │  PIN CODE:      ABC123                                 │
  │                                                        │
  │  Please enter this PIN on your CodeWithPhone Web/App.  │
  │  Waiting for your confirmation...                      │
  └────────────────────────────────────────────────────────┘

Open codewithphone.com, log in, and enter the PIN. The agent will then ask you to confirm the binding in the terminal:

  Binding request from user@example.com (John)
  Approve? [Y/n]: y
  Device authorized successfully!

Once paired, the agent starts accepting tasks.

codewithphone start -d

When using -d (daemon mode), pairing still happens interactively in your terminal — you'll see the PIN and confirm the binding just like in foreground mode. After confirmation, the agent automatically moves to the background.

Check status and stop:

codewithphone status    # show PID, listen address, machine ID
codewithphone stop      # graceful shutdown

That's it. Open codewithphone.com and start a coding session.

codewithphone start [flags]    Start the agent
codewithphone stop             Stop a running background agent
codewithphone status           Check if the agent is running
codewithphone version          Print version

# Start in foreground
codewithphone start

# Start in background (pairing is still interactive)
codewithphone start -d

# Start with a specific workspace
codewithphone start -w ~/projects

# Start in background pointing to a custom server
codewithphone start -d -s https://my-server.example.com

# Re-pair this machine (get a new PIN)
codewithphone start --bind-mode=force

# Start with a fixed port
codewithphone start -p 9090

Config is stored in ~/.codewithphone/config.yaml and is auto-created on first pairing.

daemon:
  http_addr: 127.0.0.1:0
  machine_id: machine-xxxx        # assigned by server
  machine_token: "..."            # assigned on pairing
  bind_mode: auto
  max_concurrent_turns: 10
  server_base_url: https://codewithphone.com/api
  codex_bin: codex
  gemini_bin: gemini
  gemini_model: gemini-3-flash-preview
  claude_bin: claude
  claude_model: sonnet

~/.codewithphone/
├── config.yaml         # Configuration (auto-managed)
├── codewithphone.pid   # PID file (when running in background)
├── codewithphone.log   # Log file (when running in background)
└── data/
    └── agent.db        # Local state (SQLite)

Security defaults:

• ~/.codewithphone is created with 0700
• config.yaml, codewithphone.log, and codewithphone.pid are written with 0600

All settings can be overridden via environment variables:

1. codewithphone start generates a 6-character PIN and displays it in the terminal
2. You enter the PIN on codewithphone.com while logged in
3. The agent detects your entry and prompts you to confirm in the terminal (Approve? [Y/n])
4. You press Y (or Enter) to approve, or n to reject and generate a new PIN
5. A machine token is issued and saved to ~/.codewithphone/config.yaml
6. Subsequent starts reuse the token automatically (no re-pairing needed)

With -d (daemon mode), the pairing flow runs in the foreground first. Once approved, the agent forks to the background automatically.

To re-pair (keeps the same machine ID, only refreshes the auth token):

codewithphone start --bind-mode=force

• Local confirmation required: Every new device pairing must be approved in the terminal where codewithphone is running. Even if someone knows your PIN, they cannot bind to your machine without your explicit approval.
• Token-based auth: After pairing, communication uses a machine token stored locally. No passwords are transmitted.
• Local listener: The HTTP server binds to 127.0.0.1 by default (localhost only). It is not accessible from the network.

For vulnerability reporting, see SECURITY.md.

git clone https://github.com/shotforward/codewithphone.git
cd codewithphone
make build          # produces bin/codewithphone
make test           # run tests

Each tag release uploads:

• codewithphone_<tag>_linux_amd64.tar.gz
• codewithphone_<tag>_linux_arm64.tar.gz
• codewithphone_<tag>_darwin_amd64.tar.gz
• codewithphone_<tag>_darwin_arm64.tar.gz
• checksums.txt

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md
• Trademark policy: TRADEMARK.md

Apache License 2.0