prerequisites

  • tailscale recommended (not required) on host and phone.
  • working terminal environment on the host machine.
  • go 1.24+ if building from source (prebuilt binaries don't need go).

install host

  • macos: homebrew install path
  • linux: shell installer path
  • windows: run via wsl2

reference: host installation docs

pairing

cd /path/to/your/project
pseudocoder start --pair --qr

pairing is privileged access; revoke unused devices. codes expire after 2 minutes.

  • trust mismatch triggers a hard-block -- you must re-pair from scratch
  • 5-attempt cooldown per minute to prevent brute force
  • you can also enter the code manually if the qr scan fails

first session

  1. run one small task.
  2. review one diff before apply.
  3. approve low-risk commands first.

networking

  • the host auto-selects its listen address: tailscale > lan > localhost.
  • tailscale (recommended): install on both devices, sign in with the same account. the host binds to your tailscale ip automatically.
  • trusted private network: if both devices are on the same network, the host binds to the lan ip. no extra setup needed.
  • never expose the host to the public internet.

config.toml

settings live in ~/.pseudocoder/config.toml: 

repo = "/path/to/your/project"
addr = "0.0.0.0:7070"
require_auth = true
history_lines = 5000
diff_poll_ms = 500
mdns_enabled = true

# chunk grouping
chunk_grouping_enabled = true
chunk_grouping_proximity = 5

# commit options
commit_allow_no_verify = false
commit_allow_no_gpg_sign = false
push_allow_force_with_lease = false

# daemon mode
daemon = false
pid_file = ""
log_file = ""
local_terminal = true
session_cmd = ""

# keep-awake
keep_awake_remote_enabled = false
keep_awake_allow_on_battery = true
keep_awake_auto_disable_battery_percent = 20

cli commands

  • pseudocoder start -- start the host in the current repo
  • pseudocoder start --pair --qr -- start and generate a pairing qr code
  • pseudocoder host start -- advanced daemon startup (localhost-only)
  • pseudocoder host status -- query host status + keep-awake summary
  • pseudocoder devices list -- list paired devices
  • pseudocoder devices revoke <id> -- revoke a paired device
  • pseudocoder session list -- list active sessions
  • pseudocoder session attach-tmux <name> -- attach to a named tmux session
  • pseudocoder session detach -- detach from the current session
  • pseudocoder session rename <new-name> -- rename the current session
  • pseudocoder keep-awake enable-remote -- enable keep-awake from remote device
  • pseudocoder keep-awake disable-remote -- disable keep-awake remotely
  • pseudocoder keep-awake status -- check keep-awake state
  • pseudocoder doctor -- check host health and connectivity
  • pseudocoder doctor --json -- JSON output for diagnostics
back to home →