# @p4code/cli

The P4Code server and CLI. Runs coding agents (Claude Code, Codex, OpenCode,
Cursor, Grok, Muse Code) against your local repositories and serves a web UI for driving
them, so you can start work from whichever machine you happen to be at.

Installs the `p4c` binary.

> A fork of [t3code](https://github.com/pingdotgg/t3code) by T3 Tools Inc.,
> maintained for personal use. Not affiliated with or endorsed by T3 Tools Inc.

## Requirements

**Node.js 24.13.1 or newer.** The server stores state through `node:sqlite`,
whose API only stabilised in Node 24 — on older releases it installs fine and
then fails at runtime.

You also need at least one agent CLI on your `PATH` (`claude`, `codex`,
`opencode`, `cursor-agent`), and `git`. `gh` is used for pull-request actions.

## Install

```bash
npm install -g @p4code/cli
```

## Quick start

From inside a git repository:

```bash
p4
```

That starts the server and opens the web UI. To run headless — no browser, and
it prints the pairing details you need to connect from elsewhere:

```bash
p4c serve
```

## Reaching it from another machine

Bind to an interface your other devices can see, or let Tailscale terminate
HTTPS for you on the tailnet:

```bash
p4c serve --host 0.0.0.0 --port 3773
p4c serve --tailscale-serve            # HTTPS on your MagicDNS name
```

Clients authenticate with a pairing token — the server prints one on a headless
start, and you can mint more:

```bash
p4c auth pairing --help    # one-time client pairing tokens
p4c auth session --help    # bearer sessions: list, revoke
```

## Running it in the background

Install as a per-user service so it comes back on its own:

```bash
p4c service install     # macOS: launchd LaunchAgent · Linux: systemd user unit
p4c service status
p4c service update      # re-point at the current build and restart
p4c service uninstall
```

Deliberately per-user rather than system-wide: the server reads its state from
`~/.p4`, and the agent CLIs it spawns authenticate against your own home
directory and login keychain — none of which a root-owned service would see.

**On macOS that means it starts with your login session.** For a machine you
want reachable unattended, enable automatic login in _System Settings → Users &
Groups_. Linux does the equivalent with `loginctl enable-linger`, which
`service install` handles for you.

Logs land in `~/.p4/userdata/logs/boot-service.log`.

## Commands

| Command             | What it does                        |
| ------------------- | ----------------------------------- |
| `p4c` / `p4c start` | Run the server and open the web UI  |
| `p4c serve`         | Run headless; print pairing details |
| `p4c service`       | Manage the background service       |
| `p4c auth`          | Pairing tokens and bearer sessions  |
| `p4c project`       | Add, remove, rename projects        |

`p4c --help` lists every flag; each subcommand takes `--help` too. Shell
completions are available via `p4 --completions <bash|zsh|fish|sh>`.

## Configuration

State lives in `~/.p4` by default; override with `--base-dir` or `P4CODE_HOME`.
Useful flags: `--port`, `--host`, `--mode`, `--no-browser`, `--log-level`.

## License

MIT. See [LICENSE](./LICENSE) — the upstream T3 Tools Inc. copyright is
retained, as the license requires.