# How I use AI agents: plan first, one workstream, one memory > [!summary] TL;DR > Plan first: plan mode researches and proposes changes without editing source. One workstream per task: one branch, one worktree, one tmux session, one agent conversation. One memory across harnesses: a single `AGENTS.md`, one set of guard scripts, one model router. Written state lives on disk, in `PROGRESS.md` and `TODO.md`; the chat is working memory. The series closes with agents reading an Obsidian vault and the daily system that ties it all together. ## Start here 1. [[resources/documentation/Agents/Agents - Plan First, Fresh Sessions, Write It Down|Plan first, fresh sessions, write it down]]: What does Claude Code plan mode do, what reloads in a fresh session, and where does cross-session state live? 2. [[resources/documentation/Agents/Agents - One Workstream per Task|One workstream per task]]: Why one branch, one worktree, one tmux session and one conversation per task? 3. [[resources/documentation/Agents/Agents - One Memory, Many Harnesses|One memory, many harnesses]]: How do Claude Code, pi and codex share one `AGENTS.md`, one set of guard scripts and one model router? 4. [[resources/documentation/Agents/Agents - Desktop and Remote|Desktop and remote]]: Where should a session run: cloud VM, SSH workspace or desktop app? 5. [[resources/documentation/Agents/Agents - Second Brain with Obsidian and AI|Second brain with Obsidian and AI]]: How does an agent read and query four years of Markdown notes? 6. [[resources/documentation/Agents/Agents - Daily Working System|Daily working system]]: What does a full day look like, from Things3 capture to `make check`? ## Key points - `Shift+Tab` twice switches Claude Code into plan mode: it reads files, runs commands to explore and writes a plan, but does not edit source. A planning session for 23 ADRs was a forty-minute argument about ordering with zero files touched. - Each session starts with a fresh context window. Reloaded from disk: project-root `CLAUDE.md`, auto-memory, `.claude/rules/` and the `settings.json` allowlist. The conversation is not. - Cross-session state belongs in `PROGRESS.md` (chronological, append-only; 3,012 lines and 47 sessions in one project) and `TODO.md` (pending snapshot with a handover block). Disk is the canon, chat is working memory. - One task, one branch, one worktree, one tmux session, one agent conversation. Anything shared between two tasks means the tasks eventually share a mistake. Three weeks of logs: 885 agent sessions, nearly all code work inside a task worktree, never on `main`. - Claude Code gets a deterministic session ID (uuid5 over `repo` and `branch`), so the same task always resumes the same conversation, even after a reboot. - One `AGENTS.md` serves Claude Code, pi and codex: `CLAUDE.md` is a symlink to it, pi reads `~/AGENTS.md` natively, codex reads a symlink at its own config path. - The load-bearing guard: no edits on `main` or `master` outside a worktree, ever. The same script enforces it in every harness; in Claude Code a `PreToolUse` hook, in pi a TypeScript extension. - A model router with deep, cheap and auto profiles decides which model does the work. Subagents are tiered: planners and reviewers get the big model, workers the middle one, scouts the small one. - Cloud VM sessions run in a roughly 4 vCPU / 16 GB / 30 GB ephemeral box, and the whole `.claude/` setup carries over unchanged. The desktop diff panel accepts queued inline comments, and a PR-watching agent can fix CI failures and reviewer comments; it does not press the merge button. - Starting late 2024, Claude Code, Claude Desktop and Cursor learned the Model Context Protocol, so an agent can open, search and write Markdown notes directly. The stack: `mcp-obsidian` (with the Local REST API plugin), `qmd` (BM25, local vector embeddings, a reranker) and `basic-memory`. - The vault: about four years of notes, around 3,600 Markdown files, closer to 4,000 across both vaults. An ADR written eight months earlier surfaced in a session and saved an afternoon of re-deriving the trade-off. - Daily loop: capture everything in Things3 (Monday query `P0 + High Mental Energy`), isolate each task as a workstream, gate every change with `make check` (`gofumpt`, `goimports`, `golangci-lint`, `go test -race -count=1 ./...`). - `cf`, a 1,777-line zsh function, grew into `af`, a Go CLI that manages the worktree-tmux-agent triple as a workstream with a suspend/resume/done lifecycle. Single-user, not packaged for release. - The AI's output is a draft; the test suite is the ground truth. No unread code ships. ## FAQ ### How do I plan before letting an agent edit code? Press `Shift+Tab` twice for plan mode: Claude Code researches and proposes changes without making them. The plan prompt should contain what you want, what exists, what you tried and constraints: [[resources/documentation/Agents/Agents - Plan First, Fresh Sessions, Write It Down|Plan First, Fresh Sessions, Write It Down]] ### What survives a fresh session or /compact? From disk: project-root `CLAUDE.md`, unscoped rules and auto memory. The conversation does not, which is why state belongs in `PROGRESS.md` and `TODO.md`: [[resources/documentation/Agents/Agents - Plan First, Fresh Sessions, Write It Down|Plan First, Fresh Sessions, Write It Down]] ### Why one worktree per task? One task, one branch, one worktree, one tmux session, one conversation. Anything shared between two tasks eventually shares a mistake; three weeks of logs show 885 sessions, never on `main`: [[resources/documentation/Agents/Agents - One Workstream per Task|One Workstream per Task]] ### How do I share memory between Claude Code, pi and codex? One `AGENTS.md` behind symlinks, one set of guard scripts, one model router. The habits stay above any single harness: [[resources/documentation/Agents/Agents - One Memory, Many Harnesses|One Memory, Many Harnesses]] ### Where should an agent session run? Bug fixes and small refactors go to the cloud VM (roughly 4 vCPU / 16 GB / 30 GB, ephemeral); anything needing local tooling, local secrets or a local model server goes to the SSH workspace: [[resources/documentation/Agents/Agents - Desktop and Remote|Desktop and Remote]] ### How do agents use my Obsidian notes? MCP bridges: `mcp-obsidian` plus the Local REST API plugin exposes the vault, `qmd` does retrieval (BM25, embeddings, reranking), and `basic-memory` persists observations across sessions: [[resources/documentation/Agents/Agents - Second Brain with Obsidian and AI|Second Brain with Obsidian and AI]] ### What does the daily agent workflow look like? Capture in Things3, work one task per workstream with a deterministic session ID, gate with `make check`. The AI's output is a draft; the test suite is the ground truth: [[resources/documentation/Agents/Agents - Daily Working System|Daily Working System]] ### How do I stop an agent editing main? A guard script: no edits on `main` or `master` outside a worktree, ever. It runs as a `PreToolUse` hook in Claude Code and a TypeScript extension in pi, shelling out to the same script: [[resources/documentation/Agents/Agents - One Memory, Many Harnesses|One Memory, Many Harnesses]] ## Related - [[resources/documentation/Claude Focus Workflow]] ## Sources - Series posts: how-i-use-agents, how-i-use-agents-part-2, how-i-use-agents-part-3, how-i-use-agents-part-4, second-brain-obsidian-ai-claude-code, my-daily-working-system.