An AI-powered testing layer that triages failing tests, analyzes database migrations, and verifies software changes through deterministic rules and models.
Also known as hmamut39/tewip, tewip-ai
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.83.0
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is Tewip MCP?
Tewip is an AI-powered testing layer that triages failing tests, analyzes database migrations, and verifies software changes through deterministic rules and models.
Summary generated from the project's README
About Tewip MCP server
Proving software works by triaging failing tests and analyzing database migrations is what Tewip enables for developers and SDETs. It functions as an intelligent testing layer that identifies whether a failure stems from a real bug, flaky tests, environment issues, or changed selectors. The system uses a combination of deterministic rules and AI models to provide verdicts, ensuring that it answers "cannot say" rather than guessing when evidence is insufficient.
Users can run Tewip locally via the terminal, through a VS Code extension, or as an MCP server for AI assistants like Claude and Cursor. It supports a wide range of stacks including Node.js, Python, Java, Go, .NET, Ruby, PHP, and Rust, alongside deep integration for Playwright. For teams with strict privacy requirements, it can run entirely on-device using Ollama or other local providers, ensuring no source code leaves the building. The server provides fifteen specialized tools for MCP clients, including checks for requirement coverage and next steps for project goals.
What you can do with it
- 1Diagnose failing test reportsAn AI client can use Tewip to explain why a specific test report failed and determine the root cause.
- 2Verify database migration safetyA developer can ask the tool to analyze what a migration will do to a live database before it is applied.
- 3Assess pull request riskYou can use the MCP tools to review the risks associated with a specific code change.
- 4Check requirement coverageAn AI assistant can verify if a specific requirement is currently covered and passing in the test suite.
Written from the project's README. Every use case is checked against a quote from it.
How to install Tewip MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Tewip MCP in Claude Code
$ claude mcp add --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' tewip -- npx -y tewip-aiInstall Tewip MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tewip": {
"command": "npx",
"args": [
"-y",
"tewip-ai"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Tewip MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tewip": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"tewip-ai"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Tewip MCP in VS Code CLI
$ code --add-mcp '{"name":"tewip","type":"stdio","command":"npx","args":["-y","tewip-ai"],"env":{"OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'Install Tewip MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tewip": {
"command": "npx",
"args": [
"-y",
"tewip-ai"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Tewip MCP in Codex
$ codex mcp add tewip --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- npx -y tewip-aiInstall Tewip MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tewip] command = "npx" args = ["-y", "tewip-ai"] [mcp_servers.tewip.env] OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
Install Tewip MCP in Gemini CLI
$ gemini mcp add -s user -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' tewip npx -- -y tewip-aiInstall Tewip MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tewip": {
"command": "npx",
"args": [
"-y",
"tewip-ai"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Configuration
OPENAI_API_KEYSecretOptional. Turns on the AI layer for failures the deterministic rules cannot decide. Without it only the rules run, and Tewip says which layer decided each answer.
TEWIP_ATTEST_KEYTEWIP_PROVIDER
| Name | Description | |
|---|---|---|
| OPENAI_API_KEY | Optional. Turns on the AI layer for failures the deterministic rules cannot decide. Without it only the rules run, and Tewip says which layer decided each answer. | Secret |
| TEWIP_ATTEST_KEY | — | |
| TEWIP_PROVIDER | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablehmamut39/tewip is public and reachablegithub.com/hmamut39/tewip ↗Pass
- Package names this repository as its sourcetewip-ai names hmamut39/tewip as sourcenpmjs.com/package/tewip-ai ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for tewip-ainpmjs.com/package/tewip-ai/v/0.82.0#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/hmamut39/tewip ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from tewip-aiPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTewip
Tewip (Uyghur téwip, تېۋىپ: healer, doctor) is the layer that proves software work - written by a person or by an agent.
Created and maintained by Mamuti Aishan (Hasan) (@hmamut39).
It finds why each failing test failed (a real bug, a flaky test, the environment, test data, or a changed selector), says whether a test could ever fail at all, breaks your code to find out whether the tests would notice, reads what a migration will do to a live database, and gives one verdict on whether a change is done. Every answer carries its evidence and names what decided it: a deterministic rule, the AI model, or a person's correction.
What makes it worth installing is what it refuses to say. It answers "cannot say" rather than guessing, it will not narrow a test run it cannot prove safe to narrow, and every report ends with what it did not check. Each number below was measured on strangers' real code, never on fixtures.
It works for every stack: Node.js (node:test, Jest, Vitest, Mocha), Python (pytest, unittest), Java and Kotlin (JUnit, TestNG), Go, .NET, Ruby, PHP and Rust, each checked against its real runner's report (the full list), plus Playwright in depth with traces, selector drift and verified fixes. It also reads the failure wording of the browser and component-test tools on top of those runners (Selenium, WebdriverIO, Cypress, Testing Library for React, Vue and Angular, Vue Test Utils, jest-dom and Jasmine), checked against more than 500 real messages from public projects.
| Where | How |
|---|---|
| Terminal | npm install -g tewip-ai, then tewip explain report.xml, tewip ci owner/repo --pr 12, tewip mcp |
| VS Code, Cursor, Windsurf, VSCodium | the Tewip extension (download): registers Tewip with the editor's AI assistant and adds six commands - explain a report, why CI failed on this branch, the risk review of your change, which flaky tests to quarantine, the security check, and what your corrections add up to |
| JetBrains, Claude, other AI assistants | add the MCP server tewip mcp: fifteen tools, including has this happened here before?, is this requirement covered and passing? and what should be done next about this goal? (see editor setup) |
| Any model, including none | OpenAI, Claude, Gemini, Azure, or a model on your own machine with Ollama - no account, no key, and no source code leaving the building: TEWIP_PROVIDER=ollama. Three quarters of what Tewip answers calls no model at all. How |
| GitHub CI | the Tewip Action: a comment on every pull request, an optional merge gate, verified fix PRs (QUICKSTART) |
Formerly triage-agent: the repository moved to hmamut39/tewip, and GitHub redirects the old address. See ROADMAP.md for the plan.
Status: built, and measured on other people's code. Tewip collects failures from any framework, diagnoses them with rules first and a model only for what rules cannot settle, and turns that into work for each role: a CI comment and merge gate, test plans and verified tests, a flake dossier, a PR-risk review, security scanning, tickets in Jira, Rally, GitHub Issues, Azure Boards or Linear, checks generated from a Figma design, specifications written for people, and - opt in, and only when proved - fixes to test or application code. The fix loops are built and measured, not planned: on real labelled CI failures every one of 17 locator suggestions was the locator the developers themselves wrote, a wait fix is kept only after three passes in a row, and a change to application code is kept only when the failing test passes and the whole suite still does. It runs live in GitHub CI and answers questions from AI assistants through MCP. On fresh real Gutenberg CI failures, with the pipeline frozen before labelling, accuracy is 93.4%; across six real datasets it ranges from 86.1% to 99.7%, and the caveats are in eval/README.md.
If your CI already writes a coverage report, point Tewip at it
Tewip decides what a test reaches by following imports, which is a fact rather than a name match -
and which cannot see a test that posts a GraphQL query, hits an HTTP route or renders a controller.
On a Django, Rails or Spring codebase that is most of the suite, so tewip done used to answer
"cannot say" to the question that matters most.
A coverage report settles it, and CI almost certainly produces one already. Nothing to configure:
| format | written by | found at |
|---|---|---|
lcov.info |
JavaScript, TypeScript, Rust, Go, C++ | coverage/lcov.info, lcov.info |
Cobertura coverage.xml |
pytest-cov, coverlet (.NET), simplecov | coverage.xml, coverage/coverage.xml |
| JaCoCo | Java, Kotlin | target/site/jacoco/jacoco.xml, build/reports/... |
| Clover | PHPUnit | clover.xml, build/logs/clover.xml |
With one present, done stops guessing:
### Is the changed code tested?
Yes: the suite executes saleor/graphql/utils/sorting.py.
_Decided by coverage.xml, which records what ran rather than what imports what._
and it will say the opposite just as plainly - "is in coverage.xml with no line executed, so the suite runs none of this" is a not ready, not a shrug.
What a coverage report cannot do. It records which lines ran during the whole suite, not which
test ran them, so it answers "is this code tested" and not "which tests would notice a change
here". tewip pick still narrows from imports and still refuses to narrow when it cannot show the
rest are unaffected. A report from a different checkout is ignored rather than believed: if the files
it names are not on disk, Tewip says nothing instead of reporting the whole change as untested.
Running with no data leaving the building
A hospital, a bank or a government department usually cannot send source code to a hosted API, and that is most of who this is built for. Tewip runs against a model on the same machine:
# once
curl -fsSL https://ollama.com/install.sh | sh # or ollama.com for Windows and macOS
ollama pull qwen3:8b
# then
export TEWIP_PROVIDER=ollama
tewip done --diff main...HEAD
No key, no account, no network call off the machine. TEWIP_BASE_URL points the same path at
LM Studio, vLLM, llama.cpp's server, or anything else that speaks the OpenAI shape.
What changes and what does not. The deterministic layers - vouch, schema, access, perf,
standards - call no model at any time, with any provider, and are unaffected. Only the parts that
need judgement use one: explaining a failure, writing a test, drafting a plan. A smaller local model
is less accurate at those than a frontier one, and Tewip says which layer decided every answer, so
the difference is visible rather than hidden.
A local model is also less likely to be constrained to the schema it was asked for: some backends accept the request and quietly do not enforce it. Tewip reads a reply that arrives inside a markdown fence or after a sentence of preamble, and still refuses one with no JSON in it at all.
What it costs
Most failures never reach a model. On 3,556 real CI failures from six public projects, the deterministic rules answered 75.1% on their own - and on the labelled ones they answered correctly 1,979 times out of 2,012 (98.4%). A rule-answered failure costs nothing, explains itself, and gives the same answer every time.
Only the remaining quarter is sent to a model, so triaging 1,000 real failures costs about $1.12 at gpt-5.4-mini's published price. That is measured, not estimated: three real uncached calls on held-out failures billed 3,624 prompt and 499 completion tokens each. A real week costs less, because a failure that repeats is answered from cache, and a failure someone has corrected never goes to the model again.
Tewip prints what every command costs, caps its own spend, and works with no key at all - the rules run on their own and everything they cannot settle is left as UNKNOWN rather than guessed.
Start here
npm i -g tewip-ai
cd your-project
tewip
tewip on its own looks at your project and names the two or three commands that will tell you
something, with your own paths in them — and says plainly what it cannot answer here. It reads the
directory and stops: nothing is run, nothing is written, about a second.
Here is what Tewip can tell you about **this** project, in the order worth doing.
**1. `tewip vouch`**
282 test files here (282 JavaScript or TypeScript). This reads them and names the ones
that cannot fail - no model, a second or two.
**2. `tewip schema --diff main...HEAD`**
165 migrations here (165 SQL). This says what a change would do to a live database
before it runs.
## What it will not do here
- No k6, JMeter or Lighthouse report was found. Tewip judges one you produce; it does
not run load tests itself.
Everything below is the full list, for when you want it.
Use it in your project
Giving it to your team (or another company): TEAM-GUIDE.md — what to install, what each role uses it for, and what it never does.
Putting it on a real repository: QUICKSTART.md — ten minutes, copy-paste, and what to check on the first failing run.
1. In GitHub CI (developers, SDETs, DevOps)
Tell Playwright to write a blob report in CI. It's a built-in reporter, so there's no triage-agent code in your config:
// playwright.config.ts
reporter: process.env.CI ? [['list'], ['blob']] : 'list',
use: { trace: 'retain-on-failure' },
Then add one step after your tests:
permissions:
contents: write # only needed for autofix
pull-requests: write
issues: write
actions: read # lets it read the failed job's log when no test report was written
steps:
# ... checkout, install, npx playwright test ...
- name: triage-agent
if: always()
uses: hmamut39/tewip@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }} # optional: without it only the rules run
autofix: 'true' # optional: verified locator-fix PRs
Run the verdict verbs in CI (Phase 38, new) — one step, as many checks as you want:
- uses: hmamut39/tewip@main
with:
mode: check
checks: schema, access, vouch # or: done, standards, perf, or `all`
gate: blocking # optional: fail the job on what a verb calls blocking
Every check runs even when an earlier one found something, so a pull request gets the whole picture
in one push. The gate is deliberately narrower than the report: it fails only on what the verb itself
calls blocking, because a gate that fires on advice teaches a team to pass continue-on-error. A
check with nothing to look at says so and never fails the job — no migrations in the diff is not a
pass.
Use
@mainorv0.46.0or later. Every tag before that shipped anaction.ymlwhose description contained an unquoted colon, which YAML reads as a nested mapping — the runner answered "Failed to load action.yml" and the action never ran. It is fixed, and there is now a test over the manifest so it cannot come back.
On every run, the action:
- Developers: posts one diagnosis comment on the pull request and keeps it updated. For each failure it says whether the change likely caused it, why, and what to do next.
- SDETs: writes the triage board into the job summary.
- DevOps: collects environment failures (server errors, connection resets, outages) in one GitHub issue, and each new run adds a single grouped comment to it.
- The tests in the pull request: on a PR it reads the test files the change touched and says which
of them could never fail - an unfinished expectation, a value compared with itself, a test that
discards its own failure, one that never runs. It says nothing when they are all sound, and it says
it even on a green run, because "all tests passed" is the exact sentence that needs qualifying
when one of them cannot fail. Needs
fetch-depth: 0onactions/checkoutso the diff can be read; without it the section is skipped rather than guessed at. Any such test also enters the attestation as a refusal, so a release decision taken from the bundle cannot rest on a test that proves nothing. - What the change would slip past (
prove: true): breaks the source files the pull request touched in small deliberate ways, runs the tests that cover them, and reports every change none of them noticed - "these 2 changes to your code would have slipped past your tests", with the lines. Off by default because each change costs a real test run;prove-budget(default 300s) caps the whole thing, and it says which files it did not reach rather than implying they were clean. Every file is put back exactly as it was. Each unnoticed change also enters the attestation as a refusal: a line nothing checks is not a line this bundle can claim was verified. - Evidence, every run: the Action writes an attestation into its artifact - the claims with their evidence and which layer decided each, what Tewip refused to decide, and what it did not check at all. Nothing enters it that Tewip did not verify itself, so a release decision can be taken from it without opening CI.
- Fixes (
autofix: true): for drifted locators that the deterministic rule matched to a renamed element, it rewrites the locator, re-runs that test, and opens a separate pull request with the changes that passed. It never merges and never edits application code. - Every role: uploads all role views as the
tewip-reportartifact. - When the job dies before any test runs (an image that would not pull, a runner out of disk, a service container that never came up): it reads the failed job's log and names the cause, instead of leaving a red X with no explanation.
- History: keeps the run history in the Actions cache, never in git.
- Corrections: reply to the agent's comment with
/triage CATEGORY #n reason(e.g./triage TIMING #2 flaky on CI). It stores that with the history and, next time that test fails the same way, gives the person's answer instead of its own, naming them and their reason. A corrected failure also costs nothing: it never goes to the model again.
For senior engineers, architects and leads, add a scheduled workflow with mode: report, for example weekly. It builds the engineering-quality, architecture and risk-digest views from the stored CI history, reusing earlier diagnoses so it makes no repeat AI calls. The views are kept in one GitHub issue that each report updates:
on:
schedule: [{ cron: '0 6 * * 1' }]
workflow_dispatch:
permissions: { contents: read, issues: write }
jobs:
report:
runs-on: ubuntu-latest
steps:
- uses: hmamut39/tewip@main
with: { mode: report }
The report reads the history cache of the branch it runs on, usually the default branch.
The repository needs "Allow GitHub Actions to create and approve pull requests" enabled for fix PRs. Pull requests opened by the workflow token don't trigger CI themselves; the agent verified each change by re-running the test before opening the PR. It was first proved end to end on a private practice repository, which is why there is no link to click here. If this repository is private, other repositories can only use the action when Settings → Actions → Access allows it.
As a Claude Code plugin (no account, no marketplace approval)
claude plugin marketplace add hmamut39/tewip-plugin
claude plugin install tewip@tewip
That is the whole publication process. A marketplace is a .claude-plugin/marketplace.json file in a git
repository, so Tewip publishes one at
hmamut39/tewip-plugin - nobody has to approve it, and there
is nothing to pay for. That repository holds the plugin only: a manifest, three skills and a pointer to
the npm package, which is why this one can stay private. The plugin brings Tewip's MCP server and three skills that tell Claude Code when to use it:
before claiming a change is done, when a test fails, and when a change touches a migration. It costs
about 410 tokens per session until a skill is actually needed.
The MCP server runs from the published package (npx -y tewip-ai@latest mcp), so the plugin stays small
and you always get the current version.
The editor extension (VS Code, Cursor, Windsurf, VSCodium)
Open the Extensions pane and search for "Tewip". It is in both registries, so that works in VS Code, Cursor, Windsurf, VSCodium, Gitpod and Eclipse Theia:
- VS Code — Visual Studio Marketplace
- Cursor, Windsurf, VSCodium, Gitpod, Theia — Open VSX
Or install the .vsix attached to any release with
Extensions: Install from VSIX…. Either way it needs the command line: npm install -g tewip-ai.
Press Ctrl+Shift+P and type "Tewip" for: Is this work done?, Can everybody use this?, Could
these tests ever fail?, Would the tests catch a bug in this file?, Which tests could notice this
change?, What will this migration do to a live database?, Why did CI fail on this branch?, and
more. The editor's AI assistant also picks Tewip up as an MCP server with nothing to configure.
2. From any AI assistant, through MCP (the whole IT team)
mcp/server.ts is a read-only Model Context Protocol server. Anyone on the team can ask their own assistant about test failures, in the editor or chat they already use:
| Ask your assistant | Tool it uses |
|---|---|
| "Why did CI fail on PR 12 in our-org/web?" | github_ci_report: the latest CI report for that PR, plus any verified fix PR |
| "Explain the failing checkout test" | explain_failure: root cause, confidence, evidence, history on this commit vs others, next action |
| "What should I fix first from the last run?" | triage_board (SDET) · pr_impact (developer) |
| "Is the test environment broken?" | environment_report (DevOps / SRE) |
| "Can we release?" | release_readiness (business / UAT) |
| "Where is our test suite fragile?" | quality_report (senior / principal) · architecture_report (architect) · risk_digest (lead) |
| "Write a test plan for the checkout feature in C:\work\shop" | test_plan: risks and scenarios grounded in that project's tests, code and pages; saved in its .tewip folder |
Setup, after npm install:
- Claude Code in this repo: .mcp.json is already here, so approve
tewipwhen asked. From anywhere else, runclaude mcp add tewip -- tewip mcp(installed), orclaude mcp add tewip -- node /path/to/tewip/mcp/server.ts(from a checkout). - Claude Desktop, Cursor, VS Code, and other MCP clients: add a stdio server with command
tewipand args["mcp"], or commandnodewith args["/path/to/tewip/mcp/server.ts"]from a checkout.
github_ci_report uses the gh CLI login on your machine. The other tools read the datasets under data/, and the AI layer uses OPENAI_API_KEY from .env.
Use it from your editor (any IDE that speaks MCP)
VS Code, Cursor, Windsurf and VSCodium: install the Tewip extension (extensions/vscode, packaged as tewip-<version>.vsix: Extensions → … → Install from VSIX). It registers Tewip as an MCP server by itself, so the assistant can use it with no configuration, and adds two commands: Tewip: Explain a test report… and Tewip: Why did CI fail on this branch?
Every other MCP client (JetBrains IDEs 2025.2+, Claude Code, Claude Desktop, or an editor without the extension) takes one entry. With Tewip installed from its release file (npm install -g tewip-<version>.tgz), the command is simply tewip mcp; from a checkout, point at cli/tewip.ts:
Point the entry at this checkout with an absolute path (the server resolves its own data, so the editor's working directory does not matter). VS Code uses its own shape, with a servers key and a type; put it in the workspace's .vscode/mcp.json, or in your user-level configuration (command MCP: Open User Configuration) to have it in every window:
{
"servers": {
"tewip": { "type": "stdio", "command": "tewip", "args": ["mcp"] }
}
}
Cursor, Claude Desktop, Windsurf and most other clients use the mcpServers shape (Cursor: Settings → MCP):
{
"mcpServers": {
"tewip": { "command": "tewip", "args": ["mcp"] }
}
}
- JetBrains (IntelliJ, WebStorm, PyCharm 2025.2+): Settings → Tools → MCP Server.
- Inside this repository nothing is needed for Claude Code:
.mcp.jsonis already set up.
Then ask, in plain language: "why did CI fail on my PR?", "which tests are flaky in checkout?", "is the main branch safe to release?". You can also ask it to "write a test plan for the checkout feature in C:\work\shop": the test_plan tool plans from that project's real tests, code and pages, and saves the plan in its .tewip folder. Every other tool is read-only, and github_ci_report reads the report the Action uploaded, so you can ask about a repository's CI without cloning it or opening the Actions page (it uses your gh login).
Tewip MCP questions
How do I add Tewip MCP to Claude Code?
Run claude mcp add --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' tewip -- npx -y tewip-ai in your terminal. Add --scope user to make it available in every project.
How do I add Tewip MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Tewip require an internet connection or external API?
No, you can run it locally with no data leaving your machine by using a local model provider like Ollama.
What programming languages and test frameworks does it support?
It supports Node.js, Python, Java, Kotlin, Go, .NET, Ruby, PHP, and Rust, along with tools like Playwright, Selenium, Cypress, and Jest.
How much does it cost to triage failures?
Most failures are handled by deterministic rules for free; only about 25% require a model, costing roughly $1.12 per 1,000 real failures using gpt-4o-mini.