Armitage

• 01Verified

  Citations it cannot fake

  Each reference must resolve: the file and line exist, or the Zotero page or section exists in the extracted text. It must also have been looked up in this session, so a source the model only remembers is refused.

• 02Durable

  Memory that quotes the source

  Findings are stored as the source's own words next to a link to the exact page or passage. The quote is checked against the file, even with Zotero closed and offline.

• 03Local

  Search that stays on your machine

  Embeddings, keyword search and reranking all run locally. The reranker is loaded for one query and then released, so it fits on a modest GPU.

• 04Careful

  Studies you approve

  A research plan waits for your approval. The report is refused unless every analysis paragraph cites a page or says Inference, and every quote is found on its page.

• 05Deliberate

  Designs you approve

  Before a big code change it writes a design file and asks its open questions. The plan cannot be approved with one unanswered, and editing it sends it back to draft.

• 06Consistent

  Decisions that stick

  When you settle something, Armitage records it with your own words and loads it into every later session, so nothing proposes the opposite.

• Zotero

  Your library is the source

  Armitage reads Zotero 7+ through its local API and never writes to it. Zotero stores your PDFs, EPUBs and saved web page snapshots, and Armitage reads all three, not only PDFs: PDFs page by page, with OCR for scans, EPUBs chapter by chapter, and snapshots section by section.

  Every citation opens at the exact place in Zotero, the page of a PDF or the passage of a snapshot.

• Zed

  Native in the Agent Panel

  Armitage runs inside Zed through the Agent Client Protocol. Its questions and approvals appear as native cards, and a code citation opens the file in Zed at the cited line.

• Core

  Skills & CLI

  Instructions for your coding agent, plus a CLI that maintains memory and searches your code and Zotero library. No Pi or Zed required.

• Optional · powers Zed

  Custom Pi environment

  A dedicated agent environment built around Armitage's workflow. Run it in the terminal with armitage pi, or from Zed through ACP.

• Best · needs Pi

  Zed via ACP

  Run the Pi harness in Zed's Agent Panel through the Agent Client Protocol instead of a terminal. The best way to use Armitage, and the most thoroughly tested.

1. 1

   Ask: One question

   A single query fans out across its memory, your papers and your code at once (armitage search).

2. • Memory

     armitage memory

     The agent's own notes, kept as Markdown in an Obsidian vault: plans, decisions, concepts and your profile.

   • Papers, books & web

     armitage zotero

     Your local Zotero 7+ library, read-only. Reads every file Zotero's reader opens: PDFs (with OCR for scans), EPUBs by chapter, and saved web snapshots.

   • Code

     armitage code

     An index of your repositories, shared across branches and worktrees. Looking up a symbol or where it is used needs no AI model.

3. 2

   Match: Meaning + keywords

   In each of those three sources, embedding search (Ollama) finds passages by meaning and SQLite full-text search finds exact words.

4. 3

   Rank: Best passages first

   Matches from all three sources are merged, then a reranking model (Qwen3) puts the most relevant passages first.

5. 4

   Cite: Every claim sourced

   Each factual statement carries an inline [^n] footnote to its source.

1. 1

   Sweep

   On your first fact-bearing question, it recalls memory, plans, code or literature within about three seconds and puts the evidence in front of the model.

   Earlier work is reused, not rediscovered.

2. 2

   Look up

   The agent reads the code or queries Zotero for the passages it needs.

   Claims rest on sources, not on what the model remembers.

3. 3

   Answer

   Factual answers go through an answer form with the claims and their references, not free prose.

   Every claim has a place for its source.

4. 4

   Audit

   Each footnote is checked: the file and line exist and were read, the Zotero item was returned this session and the page exists.

   Invented or half-remembered sources are rejected.

5. 5

   Correct

   If a check fails, the agent is sent back, up to three times. If it still fails, you see a visible warning and the answer is flagged.

   Nothing passes silently.

1. 1

   Extract

   Everything Zotero stores is read: PDFs page by page (scans through OCR), EPUBs by chapter, and web snapshots by section.

   Every chunk keeps its page, so a citation can name it.

2. 2

   Index

   Text is chunked, embedded with a local Ollama model into Chroma, and indexed for keywords with SQLite FTS5.

   Meaning and exact words both match.

3. 3

   Fuse

   The top 50 matches by meaning and the top 50 by keywords merge into 20 candidates by reciprocal rank fusion.

   Ranks are comparable where raw scores are not.

4. 4

   Rerank

   A Qwen3 reranker keeps the best 5. One pass orders memory, code and papers together.

   A note, a function and a paper compete on merit.

5. 5

   Cite

   Each hit carries its citation: a Zotero page, a snapshot link, a note link or a path:line.

   The index produces the citation, not the model.

• Notes and concepts

  Pointer records

  The source's exact words, linked to the page. Quick recall without paraphrasing the source.

• Research

  Plans and reports

  Approved plans and cited reports. Later sessions find what a study established.

• Design plans

  Why it was built that way

  The goal, decisions, architecture and open questions of a big change.

• Decisions

  What you settled

  Your decision, the reason and your own words. They change only by being superseded or revoked, so nothing contradicts them later.

• Profile

  Who you are to it

  Preferences, corrections, goals and dated events. It adapts to you, and the shell cannot rewrite it.

Can edit your files

• Default

  auto

  Reads what you ask and picks its own posture: answer, investigate, plan, implement or teach.

  SkillsAny skill the task names

  WorkflowNo added workflow: it picks a posture from your ask

  Draws onThe sources of whichever role it adopts

• Builder

  swe-code

  Builds a feature in small, verified steps, matching your codebase's style and proving each step with tests.

  Skillsarmitage-swe, work-patterns

  WorkflowRead the code that owns the behaviour, build in small verified steps with tests first, prove each step with the nearest gate

  Draws onFowler, Refactoring; Feathers, Working Effectively with Legacy Code; Beck, Test-Driven Development; Freeman and Pryce, Growing Object-Oriented Software

• Delivery

  swe-devops

  Handles CI/CD, releases, versioning and git, and explains as it goes. It confirms before any commit, push, tag, publish or deploy.

  Skillsarmitage-maintain, work-patterns

  WorkflowFit the process to the project, build the pipeline, confirm before any commit, push, tag, publish or deploy

  Draws onNygard, Release It!; Orosz, The Software Engineer's Guidebook; Scott, Professional CMake; the Development Container Specification

Read-only: cannot change your files

• Research

  researcher

  Answers a question from your Zotero library like a scientist: plans the study, waits for your approval, then reports with the exact page behind every claim.

  Skillsarmitage-research

  WorkflowFrame the question, write a plan, wait for your approval, read the sources, report with exact citations

  Draws onBooth et al., The Craft of Research; Booth et al., Systematic Approaches to a Successful Literature Review; Kitchenham et al., Evidence-Based Software Engineering; Spiegelhalter, The Art of Statistics

• Teaching

  tutor

  Teaches a concept, or guides you through an implementation, so you can do it alone afterwards. It never writes your code.

  Skillsarmitage-tutor

  WorkflowFind what you already know, work through examples, fade the guidance, check your understanding

  Draws onSweller et al., Cognitive Load Theory; Brown et al., Make It Stick; Fincher et al., The Cambridge Handbook of Computing Education Research; Hermans, The Programmer's Brain

• Design

  swe-plan

  Designs a feature or system, or reviews a diff, like a senior engineer and architect, naming the trade-offs.

  Skillsarmitage-swe, work-patterns, caveman-review

  WorkflowRank the quality goals, design it twice, name the trade-offs, plan in thin slices

  Draws onBass et al., Software Architecture in Practice; Ford et al., Software Architecture: The Hard Parts; Khononov, Learning Domain-Driven Design; Ousterhout, A Philosophy of Software Design

• Diagnosis

  swe-debug

  Finds why something fails before any edit and hands you a cause backed by evidence, not a guess.

  Skillswork-patterns

  WorkflowReproduce, simplify, test hypotheses, binary-chop, and stop at a cause shown with evidence

  Draws onZeller, Why Programs Fail; Agans, Debugging: The 9 Indispensable Rules; Spinellis, Effective Debugging; Taudul, Tracy Profiler User Manual

Contains the agent

• Shell

  Sandboxed commands

  Runs in bubblewrap with an empty root and no network, with SSH, AWS and GPG folders hidden. Without the sandbox, the shell refuses to run.

• Files

  File-tool guard

  Writes outside the workspace are refused, and reads outside it ask you first.

• Rules

  Protected rules

  Its skills, persona and your profile are read-only to the agent, so it cannot widen its own sandbox.

• Models

  Local only

  The CLI refuses a non-local Ollama host unless you opt in.

Keeps you in charge

• Commands

  Permission prompts

  Commands ask before running: all of them, only risky ones, or none. Allow and deny rules can be set per command.

• Roles

  Read-only roles

  The researcher, tutor, planner and debug roles cannot change your files. Their builds and tests run in a throwaway overlay.

• Library

  Zotero untouched

  Armitage never writes to your Zotero library. The one opt-in OCR option rewrites a PDF file and keeps the original.