# mexxi > A workflow that takes a coding agent's task to a pull request you can review in a minute. These docs are generated from the repository. ## Start here - [mexxi](https://alexportelli12.github.io/mexxi/docs/index.md): Coding agents write code fast. - [Getting started](https://alexportelli12.github.io/mexxi/docs/getting-started.md): Setting up mexxi takes two pastes into the agent you already use: one installs mexxi on your machine, and one prepares a repository. - [Glossary](https://alexportelli12.github.io/mexxi/docs/glossary.md): The words these docs use, what each one means, and why it matters to mexxi. - [How a run works](https://alexportelli12.github.io/mexxi/docs/how-a-run-works.md): A run is what happens between typing /wettaq, the command that builds a change, and a pull request you can review in about a minute. - [The ideas behind mexxi](https://alexportelli12.github.io/mexxi/docs/ideas.md): Coding agents can now take a whole task and hand back a pull request. - [Reviewing a mexxi pull request](https://alexportelli12.github.io/mexxi/docs/reviewing-a-pull-request.md): Checking an agent's work is now the slow part, not writing it. - [The names](https://alexportelli12.github.io/mexxi/docs/names.md): mexxi's tools are named in Maltese, the author's native language, as Verifika is. ## Configuration - [Host details](https://alexportelli12.github.io/mexxi/docs/host-details.md): mexxi works with the coding agent you already use, so you need not switch tools to get it. - [segwi](https://alexportelli12.github.io/mexxi/docs/segwi.md): A mexxi run takes minutes to an hour, and it stops whenever it needs a reply or a permission. - [Configuration](https://alexportelli12.github.io/mexxi/docs/configuration/index.md): mexxi works without any configuration. ## History - [Migrating from coding-agent-config](https://alexportelli12.github.io/mexxi/docs/migrating-from-coding-agent-config.md): mexxi used to live in ~/.config/opencode, under the name coding-agent-config. ## Principles - [Where the problems come from](https://alexportelli12.github.io/mexxi/docs/where-the-problems-come-from.md): The problems mexxi solves were measured, not guessed. - [Working with me as an AI coding partner](https://alexportelli12.github.io/mexxi/docs/principles/agents.md): You are my senior engineering deputy. - [workflow-for-alex](https://alexportelli12.github.io/mexxi/docs/principles/workflow.md): A change to one part of the workflow can quietly contradict another. ## Decisions - [0001. One shared workflow, thin host adapters](https://alexportelli12.github.io/mexxi/docs/decisions/0001-shared-workflow-host-adapters.md): mexxi runs under three coding agents: OpenCode, Claude Code and Codex. - [0002. One user config file; host files rendered at install](https://alexportelli12.github.io/mexxi/docs/decisions/0002-one-config-rendered-host-files.md): Models, paths, enabled hosts and guard rules differ from person to person. - [0003. The installer owns only what it records](https://alexportelli12.github.io/mexxi/docs/decisions/0003-installer-owns-what-it-records.md): The installer writes into folders that belong to the person, not to mexxi: ~/.claude, ~/.codex, ~/.agents/skills, ~/.config/opencode and ~/.local/bin. - [0004. One isolated worktree per task, run by ibni](https://alexportelli12.github.io/mexxi/docs/decisions/0004-isolated-worktree-per-task.md): Agents working in the person's own checkout switched branches, stashed work and left the tree dirty. - [0005. `npm run verify` is each repository's deterministic contract](https://alexportelli12.github.io/mexxi/docs/decisions/0005-verify-is-the-contract.md): Each application repository checks itself differently: lint, types, unit tests, builds and end-to-end tests in varying combinations. - [0006. Rules stay rules; deterministic layers back them up](https://alexportelli12.github.io/mexxi/docs/decisions/0006-rules-stay-rules-guard-backs-up.md): The workflow's governance prefers deterministic enforcement to prose: a check that cannot be argued with beats a sentence an agent may forget. - [0007. Implementers implement, reviewers judge](https://alexportelli12.github.io/mexxi/docs/decisions/0007-implementers-implement-reviewers-judge.md): An agent that reviews its own work tends to approve it, and a reviewer that also fixes what it finds turns review into another round of implementation. - [0008. Jev triage runs in shadow, from metadata only](https://alexportelli12.github.io/mexxi/docs/decisions/0008-jev-shadow-metadata-only.md): Each /wettaq run makes proportionality calls in prose: whether the change alters existing UI, needs rendered QA, deserves an independent review, or touches a one-way door. - [0009. Docs are generated from the files they describe](https://alexportelli12.github.io/mexxi/docs/decisions/0009-docs-generated-from-sources.md): mexxi is public and meant for other people to adopt, so it needs documentation that is easy to read and search. - [0010. Each repository names its verify command](https://alexportelli12.github.io/mexxi/docs/decisions/0010-repository-names-its-verify-command.md): Supersedes 0005. - [0011. segwi: an opt-in launcher for mexxi runs, with a web app and MCP](https://alexportelli12.github.io/mexxi/docs/decisions/0011-segwi.md): A mexxi run takes minutes to an hour, and it stops whenever it needs a reply or a permission. - [0012. segwi: three permissions modes, auto by default](https://alexportelli12.github.io/mexxi/docs/decisions/0012-segwi-permission-modes.md): Supersedes the "Strict permissions" point of 0011. - [0013. segwi: a browser and extra hosts for a run's checks, without loosening the sandbox](https://alexportelli12.github.io/mexxi/docs/decisions/0013-segwi-run-browser-and-hosts.md): A build run in a real Angular repository ran npm run verify on an untouched main, and four of its seven checks failed for reasons outside the code: - [0014. ibni installs dependencies and runs the verify command](https://alexportelli12.github.io/mexxi/docs/decisions/0014-ibni-runs-setup-and-verify.md): Supersedes 0004 and 0010. - [0015. Every test names the break it catches](https://alexportelli12.github.io/mexxi/docs/decisions/0015-tests-name-the-break-they-catch.md): /wettaq asked for proof "at the cheapest level" for important, testable criteria, and warned against low-value tests, in one short paragraph. - [0016. segwi runs are trusted like your own sessions](https://alexportelli12.github.io/mexxi/docs/decisions/0016-segwi-runs-trusted-like-own-sessions.md): Supersedes 0012, the "Strict permissions" point of 0011, and the sandbox parts of 0013 and 0014. - [0017. Each workspace gets a block of ports, and ibni hands it to setup and verify](https://alexportelli12.github.io/mexxi/docs/decisions/0017-workspace-port-blocks.md): Extends 0014. - [0018. Setup and verify wait for one of a few machine-wide slots](https://alexportelli12.github.io/mexxi/docs/decisions/0018-machine-wide-run-slots.md): Extends 0014. - [0019. Setup and verify run in a systemd scope where one can start](https://alexportelli12.github.io/mexxi/docs/decisions/0019-runs-in-a-systemd-scope.md): Extends 0014. - [0020. segwi serves local extensions behind its own sign-in](https://alexportelli12.github.io/mexxi/docs/decisions/0020-segwi-local-extensions.md): segwi already runs all the time on the machine, behind a sign-in that works from a phone (0011). - [Decisions](https://alexportelli12.github.io/mexxi/docs/decisions/index.md): Each record explains one architectural decision: the context, what was decided, its consequences and the alternatives turned down. ## Skills - [angular](https://alexportelli12.github.io/mexxi/docs/skills/angular.md): Angular has its own patterns, and generic advice gets them wrong. - [Architecture](https://alexportelli12.github.io/mexxi/docs/skills/angular/architecture.md): Reason about Angular architecture within the workspace that actually exists. - [Components](https://alexportelli12.github.io/mexxi/docs/skills/angular/components.md): Design the cleanest component boundary for the feature, not the most modern component syntax in isolation. - [Data Access](https://alexportelli12.github.io/mexxi/docs/skills/angular/data-access.md): Treat server state, request lifecycle, and view state as related but distinct design concerns. - [Forms](https://alexportelli12.github.io/mexxi/docs/skills/angular/forms.md): Choose a forms approach from the repository, Angular version, and feature needs. - [State Management](https://alexportelli12.github.io/mexxi/docs/skills/angular/state-management.md): Start by deciding whether a state-management abstraction is needed. - [Testing](https://alexportelli12.github.io/mexxi/docs/skills/angular/testing.md): test-design decides whether a behaviour earns a test, the break each test catches, its level and how to see it fail. - [commit-pr-writing](https://alexportelli12.github.io/mexxi/docs/skills/commit-pr-writing.md): A pull request you have to reverse-engineer from the diff costs more time than the agent saved. - [docs-writing](https://alexportelli12.github.io/mexxi/docs/skills/docs-writing.md): Docs written for insiders lose newcomers, so mexxi's pages need one plain voice that says why before how. - [frontend-design](https://alexportelli12.github.io/mexxi/docs/skills/frontend-design.md): Generated interfaces tend to look the same, templated and generic. - [ibda](https://alexportelli12.github.io/mexxi/docs/skills/ibda.md): The setup skill a pasted prompt points to: it installs, repairs or upgrades mexxi. - [implement-review](https://alexportelli12.github.io/mexxi/docs/skills/implement-review.md): A review only helps if its findings are fixed and confirmed once, not argued over in an endless loop. - [playwright-tests](https://alexportelli12.github.io/mexxi/docs/skills/playwright-tests.md): Browser tests with brittle selectors break on every harmless change. - [rendered-qa](https://alexportelli12.github.io/mexxi/docs/skills/rendered-qa.md): Code and stylesheets cannot show what a page actually looks like; a real browser and screenshots can. - [repo-context](https://alexportelli12.github.io/mexxi/docs/skills/repo-context.md): An agent that changes code before it understands the repository breaks the patterns already there. - [skill-creator](https://alexportelli12.github.io/mexxi/docs/skills/skill-creator.md): A skill that never loads, or loads at the wrong time, is worse than none. - [JSON Schemas](https://alexportelli12.github.io/mexxi/docs/skills/skill-creator/schemas.md): This document defines the JSON schemas used by skill-creator. - [test-design](https://alexportelli12.github.io/mexxi/docs/skills/test-design.md): Agents write tests that pass whatever the code does, so a green suite with hundreds of tests can still protect nothing. - [Test Design Examples](https://alexportelli12.github.io/mexxi/docs/skills/test-design/examples.md): One short bad and good pair per rule in SKILL.md. - [ui-designer](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer.md): Interface code written without design judgement works, but is hard to use. - [Buttons And Actions](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/buttons-and-actions.md): Use a small set of action weights: - [Colour](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/colour.md): Prefer a small semantic palette with explicit jobs, such as brand or interactive, strong and supporting text, strong and subtle stroke, surfaces, and status colours. - [Forms](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/forms.md): A single-column form gives the eye, keyboard, and error flow a predictable direction. - [UI Fundamentals](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/fundamentals.md): Use these principles to reason through cross-cutting interface decisions. - [Layout And Spacing](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/layout-and-spacing.md): Communicate relationships through proximity, alignment, visual similarity, and shared containers. - [Simplicity And Hierarchy](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/simplicity-and-hierarchy.md): Identify four layers before arranging the screen: - [Typography And Copy](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/typography-and-copy.md): Typography and language determine how quickly information can be scanned, understood, and acted on. - [UI Review](https://alexportelli12.github.io/mexxi/docs/skills/ui-designer/ui-review.md): Review the rendered interface, not only source code. - [ux-principles](https://alexportelli12.github.io/mexxi/docs/skills/ux-principles.md): Without written UX principles, every agent decides interface questions its own way. - [Skills](https://alexportelli12.github.io/mexxi/docs/skills/index.md): A coding agent cannot hold every piece of specialist know-how in its standing instructions; they would grow too long to follow. ## Commands - [/wettaq](https://alexportelli12.github.io/mexxi/docs/commands/wettaq.md): Takes a request in plain words to one tested, reviewed pull request. - [/lesti](https://alexportelli12.github.io/mexxi/docs/commands/lesti.md): Opens one pull request that gets a repository ready for mexxi. - [/ittestja](https://alexportelli12.github.io/mexxi/docs/commands/ittestja.md): Tries a page or flow in a real browser and reports what is broken, without changing code. - [/fassal](https://alexportelli12.github.io/mexxi/docs/commands/fassal.md): Writes a product's UX principles, so agents make interface decisions the way you would. - [/sewwi](https://alexportelli12.github.io/mexxi/docs/commands/sewwi.md): Audits or changes the workflow itself: its commands, skills, agents and rules. - [/irrifletti](https://alexportelli12.github.io/mexxi/docs/commands/irrifletti.md): Looks back at your recent agent sessions, privately, to show whether a change to the workflow helped. - [Commands](https://alexportelli12.github.io/mexxi/docs/commands/index.md): A command is a workflow you start by typing its name in your coding agent's chat, such as /wettaq show the last sync time on the settings page. ## Agents - [code-reviewer](https://alexportelli12.github.io/mexxi/docs/agents/code-reviewer.md): An agent that reviews its own work tends to approve it, so a separate reviewer judges the finished change. - [ui-designer](https://alexportelli12.github.io/mexxi/docs/agents/ui-designer.md): Interface work needs design judgement that general coding instructions do not carry, such as hierarchy, spacing and states. - [Agents](https://alexportelli12.github.io/mexxi/docs/agents/index.md): Here an agent is a specialist role that the main coding agent hands part of a task to. ## CLI reference - [CLI reference](https://alexportelli12.github.io/mexxi/docs/cli/index.md): The command-line tool the agent runs to give each task its own copy of the repository, and to push only the exact code recorded as passing its checks.