Guide · not normative
The Focus AI Standards
Guide: GDE-006
Status: Current
Relates to: STD-004, STD-005, STD-007, STD-008
W. Schenk
The Focus AI
2026-07-25
Verified 2026-07-26

Local development environment

Status of this guide

This is a guide: explanation, walkthrough and reference implementation. It contains no clauses and binds nothing (STD-001 §4). The rules in this area are STD-004, STD-005, STD-007, STD-008; where this document and a standard disagree, the standard is the authority.

When a guide turns out to contain a rule, the rule moves to a standard where it can be cited and checked, and the guide keeps the explanation.

Was deployment.md, which was named for deployment but contained none of it. The deployment routing it used to carry is now STD-008; the binding rules for tooling are STD-004, for agent environments STD-005, and for secrets STD-007. Everything below is the walkthrough, preserved as it was.

Setting up a working machine: mise and fnox activation, remote servers, pi, and tmux. This is explanation — the rules it satisfies live in the standards above.

mise and fnox setup

Install mise:

curl https://mise.run | sh

Install fnox:

mise use fnox

After installing mise and/or fnox, they may not be available in the current shell. Add activation to your shell config:

# bash
echo 'eval "$(/home/worker_user/.local/bin/mise activate bash)"' >> ~/.bashrc

# zsh
echo 'eval "$(/home/worker_user/.local/bin/mise activate zsh)"' >> ~/.zshrc
echo 'command -v fnox >/dev/null 2>&1 && eval "$(fnox activate zsh)"' >> ~/.zshrc

Both shells need activation. A machine where only one is configured produces the long-running confusion where a task works in one terminal and not another. STD-004 §3.7 requires this; the two eval lines are how it is satisfied.

Note that fnox activation is separate from mise activation — mise loads .fnox/env, fnox resolves the secrets themselves.

remote server setup

When manually running on a remote server:

``bash git config --global user.name "Your Name" git config --global user.email "your@email.com" ``

setting up pi

Install pi (project-level)

Add Node and pi to the project's mise.toml:

mise use node
mise use npm:@earendil-works/pi-coding-agent

Alternative: install pi globally with the install script:

curl -fsSL https://pi.dev/install.sh | sh

Project-local pi configuration

Create .pi/settings.json to keep pi resources project-local:

{
  "npmCommand": ["mise", "exec", "node", "--", "npm"],
  "sessionDir": ".pi/sessions"
}

Add to .gitignore so per-developer artifacts aren't committed:

.pi/sessions/
.pi/npm/
.pi/git/

Note: .pi/settings.json itself should be committed so the team shares the same pi configuration.

Install pi packages (project-local)

Always use -l (local) to install packages at the project level:

pi install -l git:github.com/offline-ant/pi-tmux

This writes to .pi/settings.json and installs to .pi/git/. Teammates who clone the repo and run pi will have packages auto-installed on startup.

Everything in .pi/ is pinned per project rather than globally, which is STD-004 §3.1 applied to pi. The current package set is in best-practices/GDE-007-pi-extensions.md.

tmux setup

Add to ~/.tmux.conf:

set -g mouse on
set -g extended-keys on
set -g extended-keys-format csi-u

After updating ~/.tmux.conf, restart tmux fully:

tmux kill-server
tmux

Tip: With mouse on, tmux captures mouse events. Hold Shift while selecting text to temporarily bypass tmux's mouse handling for copy/paste.