AI coding agents are good at producing code. They are also good at inventing
abstractions, dependencies, and future requirements nobody asked for.
Glasses makes the agent stop and answer:
What evidence requires this complexity now?
No evidence means no extra machinery. Correctness, security, accessibility,
data integrity, validation, observability, and useful tests are never removed.
Choose the nerd you need
| You need to… | Use | What happens |
|---|
| Create or simplify a plan | /glasses:glasses | Challenges unsupported complexity and produces an executable plan. |
| Find and fix a code problem | /glasses:pointer | Diagnoses once, recommends a correction, and asks before editing. |
| Research a technical decision | /glasses:homework | Creates a research plan, brings sources, and asks before running validation. |
| Capture notes or project docs | /glasses:scribe | Takes approved notes, maps project docs, and preserves visible memory. |
| Think through a question or decision | /glasses:brainstorm | Explores possibilities, then critiques and compares them while you choose the outcome. |
| Recover business rules from existing code | /glasses:reversa | Digs one part at a time, read-only, grades every rule by evidence, and asks before moving on. |
They can hand work to each other when needed without repeatedly bouncing the
same decision around.
Install in Claude Code
Run these commands in your terminal:
claude plugin marketplace add DanielGouveiah/glasses
claude plugin install glasses@daniskills
Restart Claude Code. That is all.
Glasses now activates automatically when Claude creates a plan, ADR, design, or
architecture proposal. Its default mode is high.
Install with Skills.sh
For Codex, Cursor, OpenCode, and other agents supported by
Skills.sh, install the portable Glasses skills with:
npx skills add DanielGouveiah/glasses
The CLI lets you choose which agent and skills to install. Add -g for a
user-level installation available across projects. This installs the portable
skills; use the Claude Code plugin installation above when you also want its
automatic session and subagent hooks.
Use it
Review a plan
/glasses:glasses
You can choose a mode:
/glasses:glasses medium
/glasses:glasses high
/glasses:glasses ultra
/glasses:glasses off
| Mode | Meaning |
|---|
medium | Remove obvious excess, but allow named near-term flexibility. |
high | Keep complexity only when current evidence requires it. Default. |
ultra | Require evidence for every new component and prefer native solutions. |
off | Disable automatic Glasses review for the session. |
Diagnose existing code
/glasses:pointer the failing checkout test
Pointer:
- Inspects the relevant code and evidence.
- Asks one numbered question at a time if needed.
- Shows the problem, options, and recommendation.
- Asks permission before changing code.
- Applies the accepted correction once, verifies it, and stops.
Research a decision
/glasses:homework best local model for structured extraction on 6GB VRAM
Homework:
- Uses your conversation and project as context.
- Keeps an explicitly general question general; project context applies only
when you ask it to.
- Always asks a numbered Q1 to confirm objective, scope, and exclusions.
- Shows a bounded research plan and waits for approval.
- Researches reliable sources and returns a recommendation.
- Suggests the cheapest bounded validation plan.
- After separate approval, runs its named experiments until the budget or
stopping condition is reached.
One validation plan may include several stages or matrix cells. Homework does
not ask again for each approved cell, but it must ask before expanding the
scope or budget.
Capture notes and documentation
/glasses:scribe document what we decided
/glasses:scribe map this project
Scribe:
- Reads existing notes and docs before writing.
- Takes session notes when explicitly requested.
- For broad project notes, first proposes the files to create or update.
- Writes only after the user requested or approved that specific note work.
- Records visible project memory only; it does not manage hidden AI memory.
Available depths are skim, study (default), and thesis.
Think through an idea or decision
Brainstorm expands possibilities and challenges assumptions. You decide.
/glasses:brainstorm
You can also ask directly for brainstorming, idea exploration, or help thinking
through a decision. Brainstorm first agrees on the session outcome, then helps
explore ideas before moving into a separate critical evaluation. It can make a
recommendation using your criteria, while leaving the decision with you. At the
start, you can choose whether to keep a visible session record; when accepted,
Brainstorm updates it after relevant decisions. A session can end with a clearer
problem or open uncertainties instead of a forced decision.
Recover business rules from existing code
/glasses:reversa the checkout module
Reversa:
- Never edits the target project; findings stay in the conversation.
- Maps the entry points of one part, digs for signals, and turns each one
into a rule in business language with
file:line evidence.
- Scores every rule's confidence from
0.00 to 100.00 (confirmed, inferred,
or gap bands, with caps), and marks whether code or only a prompt enforces it.
- Flags rules that no ADR, spec, or doc declares as restricted.
- Reports coverage for that part, then asks which part comes next.
What Glasses changes
A Glasses plan clearly states:
- required behavior and acceptance tests;
- the simplest design supported by evidence;
- complexity removed and retained;
- decisions answered during review;
- triggers that would justify more machinery later.
Implementation then stays inside that plan. If new evidence changes the design,
Glasses revises the plan explicitly instead of silently expanding the code.
Language behavior
Glasses answers in the language used by the user, including workflow headings,
questions, options, approvals, and completion reports. It does not translate
source code, identifiers, commands, file paths, configuration keys, tool names,
or error and log output. New file content follows the repository's language and
comment conventions.
Language is derived from the user's natural-language task, not control text. An
English command wrapper, injected hook, or skill instruction therefore cannot
replace the language of a Portuguese task; short acknowledgements and command
invocations also keep the established task language.
Other AI coding agents
The repository includes adapters for Gemini CLI, Codex, GitHub Copilot CLI, and
OpenCode. Claude Code currently has the most complete installation flow.
Install the Gemini extension with:
gemini extensions install https://github.com/DanielGouveiah/glasses
The portable policies live in:
CLI harness support
| Harness | Auto context | Manual route | Stepped questions | Approval gates | Scribe notes |
|---|
| Claude Code plugin | Session and subagent hooks | Skill routes | Yes, Q1, Q2 | Yes | Yes, approval-only |
| GitHub Copilot plugin | Session and subagent hooks | Skill routes | Yes, Q1, Q2 | Yes | Yes, approval-only |
| Codex plugin | Skills directory | Skill routes | Yes, Q1, Q2 | Yes | Yes, approval-only |
| Gemini CLI extension | Static Glasses context | /glasses:* commands | Yes, Q1, Q2 | Yes | Yes, approval-only |
| OpenCode adapter | Chat system transform | Adapter policy | Yes, Q1, Q2 | Yes | Yes, approval-only |
The shared routing policy is generated from
skills/glasses/scripts/workflow-routing.mjs for JavaScript harnesses. Static
harnesses keep the same routing rules in the Glasses skill and command files.
Brainstorm uses a harness's native question/options interface when the current
mode permits it, with one textual question and concise labeled options as the
fallback. Its optional session checkpoint is a visible Markdown file, saved and
updated only after the user agrees to keep a record; without file tools, the
checkpoint remains in the conversation.
Configuration
To change the automatic mode, create ~/.config/glasses/config.json:
{
"defaultMode": "high"
}
Manual /glasses:glasses use defaults to high, even if configuration says
otherwise.
Develop locally
git clone https://github.com/DanielGouveiah/glasses.git
cd glasses
npm test
npm run validate
claude --plugin-dir ./skills/glasses
License
MIT
