Getting Started

Prerequisites

Clone and Setup

git clone --recursive https://github.com/omxyz/namu.git
cd namu
./Scripts/setup.sh
xcodegen generate
open Namu.xcodeproj

Scripts/setup.sh initializes the Ghostty dependency and builds GhosttyKit.xcframework. xcodegen generate creates Namu.xcodeproj from project.yml.

Build

xcodebuild -scheme Namu -configuration Debug build

Run Tests

xcodebuild -scheme Namu -configuration Debug test

# Run a specific test suite
xcodebuild -scheme Namu -configuration Debug \
  -only-testing:NamuTests/WorkspaceTests test

Repository Layout

namu/
  NamuKit/         Core logic: domain, terminal, IPC, alerting, services, browser, remote
  NamuUI/          SwiftUI + AppKit app and views
  CLI/             `namu` CLI, hooks (Claude, Codex), tmux compat
  daemon/remote/   Go daemon for remote session and proxy RPC
  Resources/       Info.plist, shell integration, bundled CLI, skills, SDEF
  Tests/           Swift unit tests, UI tests, Python integration tests
  project.yml      XcodeGen project definition

First Run Checks

  1. Launch the Namu scheme from Xcode.
  2. Confirm a terminal workspace opens.
  3. Verify the Unix socket exists: ls /tmp/namu.sock
  4. From another terminal: namu system ping
  5. Inspect available commands: namu system capabilities --json

SSH Remote Workspace

Connect to a remote host and open a managed workspace over SSH: 

namu ssh user@remote-host
namu ssh user@remote-host --port 2222
namu ssh user@remote-host --identity ~/.ssh/id_ed25519

Namu provisions the remote daemon binary (SHA256-verified), sets up an HMAC-SHA256 authenticated relay, and optionally tunnels browser traffic via SOCKS5. The connection recovers automatically with exponential backoff.

Agent Hook Setup

Install Claude Code hooks to enable sidebar status, notifications, and session tracking:

namu claude-teams          # install Claude hooks for this workspace
namu codex install-hooks   # install Codex hooks

Config Hot-Reload

Press Cmd+Shift+, to reload Ghostty config without restarting. Project config (namu.json) is watched automatically and reloads on save.

Notes