devx

devx is a small Go CLI for opening AI coding projects inside persistent tmux sessions.

It supports project-level defaults for:

• Claude Code
• Codex CLI
• Gemini CLI
• OpenCode
• Shell-only sessions
• Any other AI CLI, declared as a custom agent

The main workflow is:

devx create novel-love-story
devx novel-love-story

When a project is opened, devx creates or reconnects to a tmux session. That makes the same AI CLI session available from a Mac terminal, SSH, Termius, or another tmux client.

• Create and Git-initialize new projects
• Register existing projects, one at a time or in bulk with devx import
• Choose Claude Code, Codex, Gemini, OpenCode, shell-only, or a custom agent per project
• Override the AI agent for a new session
• Create, attach, switch, inspect, and stop tmux sessions
• Fuzzy project name matching on open (devx nls finds novel-love-story)
• Safe behavior when invoked from inside tmux
• JSON configuration under the OS user config directory
• Dependency and configuration checks with devx doctor

Required:

• Go 1.23 or newer to build
• Git
• tmux

Optional:

• Claude Code (claude)
• Codex CLI (codex)
• Gemini CLI (gemini)
• OpenCode (opencode)
• Tailscale for secure remote access

brew install gunwooko/tap/devx

Clone the repository and build:

git clone https://github.com/gunwooko/devx.git
cd devx
go mod tidy
go test ./...
go install .

Make sure $(go env GOPATH)/bin is on your PATH.

For zsh:

echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Check the installation:

devx doctor

Set defaults:

devx config \
  --default-dir ~/Projects/personal \
  --default-agent claude

Create a project interactively:

devx create novel-love-story

Create without prompts:

devx create novel-love-story \
  --agent claude \
  --yes

Create in a custom directory:

devx create raon \
  --path ~/Projects/startup/raon \
  --agent codex

Register an existing project:

devx add novel ~/Projects/personal/novel --agent claude

Register every subdirectory of a directory at once (use --dry-run to preview):

devx import ~/Projects/personal --agent claude

Open it:

devx novel

The explicit equivalent is:

devx open novel

Use another agent for a newly created tmux session without changing the project default:

devx open novel --agent codex

If the session is already running, devx reconnects to that session. Stop it first to start a new session with a different agent:

devx stop novel
devx open novel --agent codex

devx agent novel codex

This never deletes project files:

devx remove novel

Use --force to stop an active session before removing:

devx remove novel --force

By default, macOS uses:

~/Library/Application Support/devx/config.json

Linux generally uses:

~/.config/devx/config.json

Example:

{
  "defaultProjectsDir": "/Users/gunwoo/Projects/personal",
  "defaultAgent": "claude",
  "projects": {
    "novel": {
      "path": "/Users/gunwoo/Projects/personal/novel",
      "agent": "claude"
    },
    "raon": {
      "path": "/Users/gunwoo/Projects/startup/raon",
      "agent": "codex"
    }
  }
}

Use a custom configuration file:

devx --config /path/to/config.json list

Built-in agents are claude, codex, gemini, opencode, and none. Any other AI CLI can be declared under customAgents in the config file — no devx release required:

{
  "customAgents": {
    "aider": {
      "name": "Aider",
      "command": "aider --model gpt-4o"
    }
  }
}

The key is the agent id used everywhere an agent can be named (devx create --agent aider, devx agent novel aider, defaultAgent). name is an optional display name. command must be a plain executable with simple arguments; shell operators such as ;, |, $(), and quotes are rejected, and a custom id cannot shadow a built-in agent. devx doctor reports whether each custom agent's command is valid and installed.

On the Mac:

devx novel

Detach from tmux without stopping the agent:

Ctrl-b d

From a phone over SSH:

devx novel

devx reconnects to the same tmux session. You do not need to cd into the project directory first.

Claude Code's Remote Control (claude --rc) lets you drive a session from the Claude mobile app or claude.ai/code without SSH. The two compose well: run claude --rc inside a devx-managed tmux session and you get the app experience on your phone plus a persistent full shell — logs, tests, git — when you need more than the conversation. The tmux session also keeps working for agents without a remote-control feature (Codex, Gemini, OpenCode, custom agents) and needs no relay, so it works over plain SSH or Tailscale on any network.

go mod tidy
go test ./...
go vet ./...
go build ./...

• devx does not manage SSH keys, VPNs, or Tailscale ACLs.
• The config file is written with user-only permissions where supported.
• Project files are never deleted by devx remove.
• Built-in agent commands come from a fixed allowlist. Custom agents are defined only in your own config file, and their commands are validated to reject shell operators before reaching tmux.

• Optional TUI project picker

MIT