# Configure the agent
agentdeck init

# Install as a system service (recommended)
agentdeck service install --start

# Or run in foreground
agentdeck start --foreground

Commands

Command	Description
`agentdeck init`	Interactive configuration wizard
`agentdeck start`	Start the agent (daemon mode)
`agentdeck start --foreground`	Start in foreground
`agentdeck stop`	Stop the agent
`agentdeck status`	Show agent status
`agentdeck logs [-f]`	View agent logs
`agentdeck service install`	Install system service
`agentdeck service uninstall`	Remove system service
`agentdeck service start/stop/restart`	Control service
`agentdeck hooks install`	Install Claude Code hooks
`agentdeck update`	Update to latest version
`agentdeck doctor`	Diagnose issues

System Service

The agent can run as a system service that starts automatically on boot:

macOS (launchd):

agentdeck service install --start
# Config: ~/Library/LaunchAgents/com.agentdeck.agent.plist
# Logs: ~/Library/Logs/agentdeck-agent/

Linux (systemd):

agentdeck service install --start
# Config: ~/.config/systemd/user/agentdeck-agent.service
# Logs: journalctl --user -u agentdeck-agent

Configuration

Configuration is stored in ~/.agentdeck/config.json:

{
  "machine": {
    "id": "unique-machine-id",
    "name": "My Mac"
  },
  "agent": {
    "port": 4678
  },
  "projects": {
    "basePath": "~/Dev"
  }
}

Claude Code Hooks

The agent includes hooks that notify when Claude Code sessions stop:

agentdeck hooks install   # Install hooks
agentdeck hooks status    # Check status
agentdeck hooks update    # Update to latest

Codex Notifications

Codex supports a notify hook command. Configure it to point to the agentdeck hook script:

notify = ["bash", "~/.agentdeck/hooks/notify-agentdeck.sh"]

If ~/.codex/config.toml exists, agentdeck hooks install will try to add this line for you.

Troubleshooting

agentdeck doctor

License

MIT - AgentDeck

Keywords

claude terminal remote ai cli agentdeck agentdeck