Running the Godding Repo from Your Phone¶

The phone is a three-surface control system for the swarm: GitHub Actions (no terminal needed, any agent — Claude/Gemini/Kimi/Codex), SSH into your desktop (full power, existing aliases), and native terminal app (Termux/iSH with keys configured locally). The kill switch is one tap away at all times. The right path depends on whether you have a key, a terminal, and how much you want to spend.

🌱 seedling tended 2026-05-21 research protocol mobile operations workflows github-actions multi-agent

flowchart LR
  phone[phone] --> gha[GitHub Actions<br/>mobile app · gh CLI]
  phone --> ssh[SSH → desktop<br/>existing aliases]
  phone --> term[terminal app<br/>Termux · iSH]
  phone --> clapp[Claude app<br/>claude.ai]
  gha --> claude[claude agent]
  gha --> gemini[gemini agent]
  gha --> kimi[kimi agent]
  gha --> codex[codex agent]
  ssh --> gy[gy · cy · ky aliases]
  term --> keys[.env / config files]

Two-sentence definition¶

Phone-based swarm control splits into GitHub Actions (zero setup, any agent, runs in CI) and local terminal access (SSH to desktop or native Termux/iSH with keys configured). The kill switch lives in one file and one tap halts the whole system regardless of which path you use.

The four phone paths¶

Path	Requires	Cost	Best for
GitHub Actions	GitHub app or `gh` CLI + API secrets in repo	API credits or $0	Triggering any agent without a local terminal
SSH → desktop	Terminal app + SSH key	Your desktop's existing API keys	Full swarm power via pre-configured aliases
Native terminal (Termux/iSH)	Terminal app + keys configured in `.env`	API credits	Running directly on phone without desktop
Claude app	claude.ai account	Subscription/credits	Quick ideation; no git ops

Surface 1 — GitHub Actions (primary, no terminal needed)¶

One-time setup: add API secrets to the repo¶

Go to repo → Settings → Secrets and variables → Actions → New repository secret and add whichever keys you plan to use. You only need the ones for agents you intend to run.

Secret name	Where to get the key	Required for
`ANTHROPIC_API_KEY`	console.anthropic.com → API Keys	`agent: claude`
`GEMINI_API_KEY`	aistudio.google.com/app/apikey	`agent: gemini`
`MOONSHOT_API_KEY`	platform.moonshot.ai/console/api-keys	`agent: kimi`
`OPENAI_API_KEY`	platform.openai.com/api-keys	`agent: codex`

queue-investigation never calls any AI and needs no secrets.

Triggering via GitHub mobile app¶

Open the GitHub app.
Navigate to the godding repository.
Tap the Actions tab.
Find Mobile Godding and tap it.
Tap Run workflow (top right).
Fill in the inputs (see below) and tap Run workflow.

The run appears in the Actions list. Tap it to watch live logs. On completion, the output is committed and pushed automatically.

Workflow inputs¶

Input	Required for	Options / default
`command`	all	`new-investigation` · `queue-investigation` · `swarmgod` · `forage` · `swarmgodforage`
`agent`	live commands	`claude` (default) · `gemini` · `kimi` · `codex`
`topic`	`new-investigation`, `queue-investigation`, `forage`	free text, e.g. `liver`
`notes`	optional	seed context passed into the prompt
`max_budget_usd`	claude agent only	default `6`

Which command × agent to choose¶

Goal	Command	Agent
Queue a topic, spend nothing	`queue-investigation`	(ignored)
Write a new investigation page	`new-investigation`	`claude` (best tool use)
Autonomous orient-and-act pass	`swarmgod`	`claude`
Literature / web research pass	`forage`	`gemini` (1M ctx, cheap)
Long research chain with thinking	`forage`	`kimi` (K2, 256k, reasoning)
Code-heavy agentic task	`swarmgod`	`codex` (gpt-5.4)
Orient + literature in one pass	`swarmgodforage`	`claude` or `gemini`

What the workflow does under the hood¶

ubuntu-latest runner spins up
↓
Install agent CLI (npm or pip, conditional on agent input)
↓
Kill-switch gate   → exit 1 if tasks/KILL-SWITCH.md has "status: active"
↓
API key gate       → exit 1 if matching secret is absent
↓
Build prompt       → /tmp/mobile-prompt.txt
↓
Run agent:
  claude  →  claude --print "$PROMPT" --dangerously-skip-permissions --max-budget-usd N
  gemini  →  gemini -p "$PROMPT" -y --skip-trust
  kimi    →  kimi --print --final-message-only -m k2 -y -p "$PROMPT"
  codex   →  codex exec -a never -s workspace-write "$PROMPT"
↓
git commit + push any uncommitted state changes

Triggering via `gh` CLI (phone terminal or desktop)¶

# Queue a topic — zero cost, no AI
gh workflow run mobile-godding.yml \
  -f command=queue-investigation \
  -f topic="sleep debt"

# New investigation, claude agent, $4 cap
gh workflow run mobile-godding.yml \
  -f command=new-investigation \
  -f agent=claude \
  -f topic="liver" \
  -f notes="focus on fatty liver and NAFLD" \
  -f max_budget_usd=4

# Forage with Gemini (1M context, cheaper per token)
gh workflow run mobile-godding.yml \
  -f command=forage \
  -f agent=gemini \
  -f topic="mitochondria aging"

# Kimi K2 research chain with thinking
gh workflow run mobile-godding.yml \
  -f command=swarmgodforage \
  -f agent=kimi \
  -f notes="focus on the compressibility frontier"

# Codex for code-heavy agentic task
gh workflow run mobile-godding.yml \
  -f command=swarmgod \
  -f agent=codex

# Watch the run live
gh run watch

Surface 2 — SSH into your desktop (full swarm power)¶

If your desktop is running and reachable, SSH from a phone terminal gives you the full multi-agent setup already configured there — no new key setup needed.

Terminal apps for SSH¶

App	Platform	Notes
Termux	Android	Best Android terminal; install via F-Droid for latest version
iSH	iOS	Alpine Linux shell; full SSH client built in
Blink Shell	iOS	Premium SSH client with mosh support; best iOS option
Prompt 3	iOS	Polished commercial SSH client

SSH setup (one-time on phone)¶

# In Termux or iSH — generate a key if you don't have one
ssh-keygen -t ed25519 -C "phone"

# Print the public key, then paste it into
# ~/.ssh/authorized_keys on your desktop
cat ~/.ssh/id_ed25519.pub

# Connect (replace with your desktop's IP or hostname)
ssh canac@192.168.1.x

# For remote access outside your home network:
# Install Tailscale on both phone and desktop (tailscale.com)
# then connect via Tailscale IP — works through any NAT

Once connected: the existing aliases¶

All four agents are pre-configured in ~/.bashrc on the desktop. From the SSH session:

cd $GODDING_REPO   # /mnt/c/Users/canac/REPOSITORIES/godding/godding

# Claude Code — full swarm, headless
claude --print "$(cat .claude/commands/swarmgod.md)" \
  --dangerously-skip-permissions --max-budget-usd 6

# Gemini — YOLO mode (uses desktop OAuth, no API key needed)
gy          # alias: gemini --yolo --skip-trust

# Codex — never-ask approval, workspace sandbox
cy          # alias: codex -a never -s workspace-write

# Kimi K2 — auto-approve, research chains
ky          # alias: kimi -y

# Live swarm dashboard (15s refresh orient output)
swarm-watch

# One-shot status
swarm-status

# Recent commits
swarm-git

Gemini on the desktop uses OAuth (personal account), so no GEMINI_API_KEY is needed via SSH. In CI (GitHub Actions) it uses the API key instead — the two paths authenticate differently.

Surface 3 — Native terminal app (phone without desktop)¶

Running agents directly on the phone without connecting to a desktop. More setup, fully independent.

Termux setup (Android)¶

# F-Droid version recommended over Play Store
pkg update && pkg upgrade
pkg install python nodejs git gh openssh build-essential

# Clone the repo
gh auth login
gh repo clone <your-username>/godding
cd godding/godding

# Python deps
pip install PyYAML kimi-cli

# Node CLI agents — install only what you need
npm install -g @anthropic-ai/claude-code   # Claude
npm install -g @google/gemini-cli          # Gemini
npm install -g @openai/codex               # Codex
# kimi is already installed via pip above

iSH setup (iOS — Alpine Linux)¶

apk update
apk add python3 py3-pip nodejs npm git openssh

pip3 install PyYAML kimi-cli

npm install -g @anthropic-ai/claude-code
npm install -g @google/gemini-cli
npm install -g @openai/codex

Setting API keys locally¶

The .env file in the repo root is already .gitignored — safe to add secrets there.

nano .env    # or vi, or any editor available

Add whichever keys you have (you don't need all of them):

# Anthropic — console.anthropic.com → API Keys
ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini — aistudio.google.com/app/apikey
GEMINI_API_KEY=AIza...

# Moonshot / Kimi — platform.moonshot.ai/console/api-keys
MOONSHOT_API_KEY=sk-t...

# OpenAI / Codex — platform.openai.com/api-keys
OPENAI_API_KEY=sk-proj-...

Load them into the current session:

set -a; source .env; set +a

Persist across sessions (add to ~/.bashrc in Termux or ~/.profile in iSH):

echo 'set -a; source /path/to/godding/godding/.env; set +a' >> ~/.bashrc

Kimi-specific config (`~/.kimi/config.toml`)¶

Kimi also reads from its own config file. Create it if absent:

mkdir -p ~/.kimi
cat > ~/.kimi/config.toml << 'EOF'
[providers.moonshot]
type = "openai_legacy"
base_url = "https://api.moonshot.ai/v1"
api_key = "sk-t..."

[models]
k2      = { provider = "moonshot", model = "kimi-k2.6" }
v1-auto = { provider = "moonshot", model = "moonshot-v1-auto" }

[defaults]
model = "k2"
EOF
chmod 600 ~/.kimi/config.toml

Use api.moonshot.ai/v1 (global endpoint) — not .cn or kimi.com, those return 401 for API keys.

Running agents natively on phone¶

cd /path/to/godding/godding

# Claude — headless swarmgod pass
claude --print "$(cat .claude/commands/swarmgod.md)" \
  --dangerously-skip-permissions \
  --max-budget-usd 4

# Gemini — headless forage (needs GEMINI_API_KEY, not OAuth)
gemini -p "$(cat .claude/commands/forage.md)" -y --skip-trust

# Kimi K2 — headless research with thinking
kimi --print --final-message-only -m k2 -y \
  -p "$(cat .claude/commands/swarmgod.md)"

# Codex — non-interactive exec
codex exec -a never -s workspace-write \
  "$(cat .claude/commands/swarmgod.md)"

# After any run, push state
git add docs/ tools/ tasks/ memory/
git commit -m "[mobile-native] state: session complete"
git push

Surface 4 — Claude app (claude.ai)¶

The Claude app on iOS/Android is a conversation interface, not an agent runtime. It cannot run Python tools, commit to git, or trigger workflows.

Task	Claude app	Notes
Draft an investigation page outline	Yes	Copy output → paste into GitHub app file editor
Think through a frontier or domain	Yes	Good for ideation on the go
Run `tools/orient.py`	No	Requires Python runtime
Commit and push to the repo	No	No git access
Trigger GitHub Actions	No	Use GitHub app for that
Read repo files	Possible with MCP GitHub	Needs GitHub MCP server configured

Practical workflow using only the Claude app: 1. Ask Claude to draft an investigation page (paste a snippet of an existing page as style reference). 2. Copy the output. 3. Switch to GitHub app → navigate to docs/investigations/ → tap + → create file → paste. 4. Commit directly in the GitHub app to main.

Slower than Actions but works with zero local setup and zero CLI.

Kill switch — halt everything from phone¶

Edit tasks/KILL-SWITCH.md directly in the GitHub app:

Open the repo in the GitHub app.
Navigate to tasks/KILL-SWITCH.md.
Tap the pencil (edit) icon.
Change status: INACTIVE → status: active.
Commit directly to main.

Every workflow (mobile, autoswarm-cron, any concurrent session) checks this file at startup and aborts if active. Re-enable: set back to status: INACTIVE.

Background path — autoswarm-cron (no trigger needed)¶

autoswarm-cron.yml fires every 4 hours using ANTHROPIC_API_KEY with a $12 cap. Your phone is the override, not the engine:

Queue to inject a topic before the next window.
Trigger to act right now without waiting.
Kill switch to pause everything.

Budget reference¶

Agent	Command	Typical cost	Hard cap mechanism
`queue-investigation`	any	$0	$0 (no AI)
claude	new-investigation	$1–3	`max_budget_usd` input
claude	swarmgod	$3–8	`max_budget_usd` input
gemini	forage / swarmgod	$0.50–2	model pricing (no cap)
kimi	swarmgodforage	$1–4	model pricing (no cap)
codex	swarmgod	$1–5	model pricing (no cap)
claude	autoswarm-cron	$3–10	$12 hardcoded in yml

Gemini and Kimi are cheaper per token — use them for literature-heavy forage passes. Claude remains best for tool-use-heavy swarmgod runs.

Failure modes¶

Problem	What to check
"API key gate" fails	Secret name must match exactly: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `MOONSHOT_API_KEY`, `OPENAI_API_KEY`
Kill-switch gate aborts	`tasks/KILL-SWITCH.md` has `status: active` — intentional or leftover from a previous session
Kimi 401 in CI	Use `api.moonshot.ai/v1` endpoint (global) — `.cn` and `kimi.com` endpoints reject API keys
Gemini auth error in CI	Desktop uses OAuth; CI needs `GEMINI_API_KEY` from aistudio.google.com, not the OAuth flow
Codex hangs in CI	Use `codex exec` (non-interactive), not `codex` (interactive TUI)
`gh workflow run` "not found"	Run `gh auth status` — wrong account or repo
SSH from phone times out	Check desktop SSH is running; or use Tailscale to punch through NAT
Termux npm install fails	Run `pkg install build-essential` first for native compilation
kimi-cli not found in Termux	`pip install kimi-cli` — it's a Python package, not npm

Killing fact¶

The phone adds one thing a desktop doesn't have: you always have it. The two operations most likely needed away from a desk are injecting a topic you just thought of and hitting the kill switch when something looks wrong. Everything else is a bonus.

Cross-references¶

docs/COMMANDS.md — full verb vocabulary
docs/HUMAN-GUIDE.md — what the human side costs empirically
SWARM.md — the canonical orient→act→compress loop (root of repo, not in site)
tasks/KILL-SWITCH.md — the file that halts the swarm

References¶

.github/workflows/mobile-godding.yml (cited in body) — primary source for GitHub Actions-based control; supports claude/gemini/kimi/codex agents without a local terminal.
.github/workflows/autoswarm-cron.yml (cited in body) — always-on background path; enables swarm runs without manual triggering.
tailscale.com/kb (cited in body) — zero-config VPN for phone-to-desktop SSH through any NAT; the key infrastructure for the SSH path.
docs/COMMANDS.md (referenced implicitly) — swarm verb inventory; the commands these phone-access paths invoke.