AgentNoise

1. What AgentNoise is

AgentNoise is a native desktop helper for talking to local coding agents from a phone. It uses White Noise as the private chat surface, then launches local tools through the same launcher stack used everywhere else on this site.

The design goal is narrow: a phone can ask for work, AgentNoise authenticates and routes the request, and the workstation decides what the agent process is allowed to touch.

2. Architecture

Each White Noise group id maps to its own AgentNoise session, so multiple chats can keep separate selected repos, working directories, jobs, and prompt context.

3. Release split

The two formulas use separate config, data, logs, keychain namespace, service label, and phone pairing. Do not pair the Dark Matter alpha to your main identity unless that is the test.

4. Install path

The intended packaged path is Homebrew. For the stable White Noise mainline formula, first set up direct raw Codex/Claude mode or provide hardened codex-agentnoise / claude-agentnoise bondage profiles.

brew install nvk/tap/agentnoise
agentnoise init --direct-agents
agentnoise up --direct-agents --no-listen
brew services start nvk/tap/agentnoise
agentnoise worker start --tmux

Homebrew keeps the White Noise transport alive. The worker runs phone-launched Codex, Claude, Hermes, and wiki jobs from a login shell or tmux so the CLIs see the same session and local permissions you use manually. For a single foreground debug process, stop the service and run agentnoise up --direct-agents.

For the Dark Matter alpha, use the isolated command and service:

brew install nvk/tap/agentnoise-darkmatter
agentnoise-dm up --direct-agents
brew services start nvk/tap/agentnoise-darkmatter
agentnoise-dm worker start --tmux

From source:

git clone https://github.com/nvk/agentnoise.git
cd agentnoise
cargo build --release
target/release/agentnoise up --direct-agents

The Homebrew stable formula packages wn and wnd beside AgentNoise. Source builds can install the White Noise CLI tools into AgentNoise's managed data directory if they are missing:

agentnoise whitenoise install

5. Pair the phone

1. Open the local console with agentnoise up or agentnoise-dm up from a normal user terminal.
2. Scan the desktop QR from White Noise on the phone.
3. Create a White Noise chat with the AgentNoise desktop identity.
4. Send the 6-digit PIN shown on the desktop as the first phone message.
5. Send /status, then /help.

During first pairing, AgentNoise ignores messages until the PIN succeeds. After that it saves the phone sender to the allowlist.

6. Chat commands

AgentNoise commands are not shell text. They are narrow chat verbs mapped to structured argv arrays.

/status
/repos
/use sandbox
/pwd
/codex fix the failing test
/claude review the last change
/wiki ingest this attachment and summarize it
/jobs
/tail <job>
/cancel <job>

Repos are aliases from config, not arbitrary paths sent from the phone. A plain /codex or /claude uses the current selected repo for that White Noise chat.

7. Media and wiki ingest

White Noise media sent by the phone is accepted automatically. AgentNoise saves supported attachments under .agentnoise/attachments/<attachment-id>/ inside the selected repo or worktree, then adds the local file paths to the prompt when the media arrives with a caption or work-chat follow-up.

The workspace-local attachment path is readable by the default bondage/nono agent profiles because it sits inside the same workdir passed to the agent. /wiki media prompts are framed for the LLM Wiki file-ingestion workflow so the wiki can create raw metadata stubs before continuing the requested task. /attachments, /attach <id>, and /download <id> expose saved metadata and local paths. When a completed job references a supported media file it created in the selected repo or worktree, AgentNoise uploads that file back through White Noise.

8. Fake-phone testing

The default Homebrew-built binary includes a fake-phone harness and TUI. It uses a separate White Noise daemon data directory and a throwaway phone identity, so users can test pairing, commands, handoffs, and media without touching the real phone account.

agentnoise fake-phone plan
agentnoise fake-phone tui --pin 123456
agentnoise fake-phone roundtrip --pin 123456 /status
agentnoise fake-phone roundtrip \
  --timeout-seconds 180 \
  --min-replies 2 \
  --require-job-final \
  --expect agentnoise-e2e-ok \
  /codex "Reply with exactly: agentnoise-e2e-ok"

Inside agentnoise fake-phone tui, local commands start with :. Use :attach <path> [caption] to send supported media, :chats to list followed chats, :use <number|group-prefix> to switch chats, and :quit to exit.

9. Security rules

• Use a dedicated White Noise desktop identity for AgentNoise.
• Keep the helper nsec in the OS keychain for normal use.
• Require first-pairing PIN auth before accepting any sender.
• Use repo aliases, not phone-provided filesystem paths.
• Route agent execution through bondage profiles.
• Keep default profiles sandboxed; make wider profiles explicit.
• Use local job logs, /tail, and /cancel instead of dumping raw process output into chat.

10. Optional Hermes

Hermes support is a backend, not a second messaging gateway. Keep White Noise as the phone control plane and launch Hermes through its own bondage profile.

[agents.hermes]
enabled = true
profile = "hermes"
bin = "hermes"

bondage exec hermes ~/.config/bondage/bondage.conf -- \
  hermes chat --quiet --source agentnoise --toolsets skills -q "<prompt>"

Put HERMES_HOME, model endpoint settings, toolsets, and filesystem policy in the Hermes profile. Start narrow, then widen only after the local profile behaves.

11. Troubleshooting