lousho
TypeScript AI agent SDK: offline CI evals, durable runs, human approvals, MCP. Runs in your own Node process.
Install / Use
claude mcp add LinuxDevil -- npx -y github:LinuxDevil/loushoIf the server publishes to npm under a different name, use that package instead ā check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of lousho
lousho scores 73/100 on our quality scale, 860th of 958 AI & Machine Learning skills we index.
Its MCP Server is 9.9 KB long, well organised into 14 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated yesterday, so lousho is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit ā read the skill file before letting an agent act on it.
lousho compared with similar skills
All 4 of these similar skills score higher than lousho; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| lousho (this skill)by LinuxDevil | 73 | 10 | 1d ago | MCP Server |
| claude-memby thedotmack | 100 | 117.7k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.4k | 9d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.9k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install lousho?
- Run
claude mcp add LinuxDevil -- npx -y github:LinuxDevil/lousho. The install tabs above show the steps for each supported agent. - Which AI agents does lousho work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is lousho safe to use?
- It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is lousho still maintained?
- The repository was last updated yesterday, so lousho is actively maintained.
Skill content
View source on GitHubLousho ā TypeScript AI agent SDK
</div>TypeScript AI agents you can test in CI, pause for approval, and resume after a crash. Runs in your own Node process.
<div align="center"> <a href="https://lousho.com/agent-forge"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/studio-trace-dark.png"> <img alt="Lousho Studio, the local studio, showing one agent run as a trace" src="docs/images/studio-trace.png" width="560"> </picture> </a> <br> <sub>Lousho Studio, the local studio. Open it with <code>npx lousho-studio</code> (a separate install).</sub> </div>
Why Lousho
- Test agents in CI without an API key.
lousho evalrecords a real run once, replays it with no network, and reports when the tool-call trajectory drifts. Evals - Resume after a crash. Give the agent a store and
agent.resume()finishes an interrupted run. Tool calls that already have a result do not run again. Durable execution - Pause for a human. A tool marked
needsApprovalpauses the run. Another request, or with a durable store another process, can approve it later, and the run continues where it stopped. Approvals - Runs in your own Node process. There is no hosted runtime.
lousho buildtargets a Node server, Docker or Cloudflare Workers, and Lousho Studio (lousho-studio, a separate install) runs on your machine. Deployment - Works with the Vercel AI SDK.
fromAiSdk()andfromAiSdkTools()wrap AI SDK models and tools, so you can move over one piece at a time. Migrating from the AI SDK
Try it in 60 seconds, no API key
You need Node.js 22.19 or newer and a network connection to install packages. You do not need an API key.
npm create lousho@latest my-agent -- --yes
cd my-agent
npm test
--yes picks the defaults: the minimal template and the OpenAI provider. npm test runs the project's tests on a mock model, offline.
Now add an eval. Save this as src/weather.eval.ts:
import { createAgent, defineEval, defineTool } from 'lousho';
import { mockModel } from 'lousho/testing';
import { z } from 'zod';
const getWeather = defineTool({
name: 'get_weather',
description: 'Current weather for a city',
input: z.object({ city: z.string() }),
execute: async ({ city }) => ({ city, tempC: 21, sky: 'sunny' }),
});
defineEval({
name: 'weather advice',
agent: () =>
createAgent({
instructions: 'Check the weather before giving advice.',
tools: [getWeather],
provider: mockModel([
{ toolCalls: [{ name: 'get_weather', args: { city: 'Lisbon' } }] },
{ text: 'It is sunny and 21°C. Wear a T-shirt.' },
]),
}),
async test(t) {
await t.send('What should I wear in Lisbon today?');
t.completed();
t.calledTool('get_weather', { args: { city: 'Lisbon' } });
t.maxSteps(4);
},
});
Then run it:
npx lousho eval
EVAL CASE RESULT SCORES DURATION
weather advice - PASS - 14ms
1 eval(s): 1 passed, 0 failed, 0 with soft failures (14ms)
To test against a real model, use model: 'openai/gpt-4.1-mini' in place of provider, set your key and record once. This step needs the key. Commit the cassettes it writes. CI then replays them with no network and no key:
npx lousho eval --record
npx lousho eval --replay
npx lousho eval --drift
--drift re-records each case and shows where the tool calls, arguments or step count changed. See Record, replay and drift.
How it compares
| | Lousho |
| --- | --- |
| Where it runs | In your own Node process. No hosted runtime. |
| Tests without an API key | mockModel scripts, and recorded cassettes that lousho eval --replay plays back offline |
| Crash recovery | agent.resume() on memory, file, SQLite or Cloudflare KV stores |
| Human approval | needsApproval pauses the run; with a durable store, another process can resume it |
| License | MIT |
For a side-by-side look at the Vercel AI SDK, OpenAI Agents SDK, Mastra and LangGraph.js, see the comparison page.
Installation
Requires Node.js 22.19 or newer. To start a new project, see Try it above. To chat with that agent, copy .env.example to .env, put your API key in it and run npm run dev.
To add Lousho to an existing project:
npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
See Installation for other providers. npx lousho doctor checks your setup and prints a fix for anything missing.
Quickstart
This file uses top-level await, so it must be an ES module (.mts, or "type": "module" in package.json). Set OPENAI_API_KEY to run it.
import { createAgent, defineTool } from 'lousho';
import { z } from 'zod';
const getWeather = defineTool({
name: 'get_weather',
description: 'Current weather for a city',
input: z.object({ city: z.string() }),
execute: async ({ city }) => ({ city, tempC: 21, sky: 'sunny' }),
});
const agent = createAgent({
model: 'openai/gpt-4.1-mini',
instructions: 'You are a travel assistant. Check the weather before giving advice.',
tools: [getWeather],
});
const { text } = await agent.send('What should I wear in Lisbon today?');
console.log(text);
Agent folders
An agent can also be a folder, which you run with npx lousho dev ./my-agent:
my-agent/
āāā agent.json # Optional: model, permissions, limits
āāā instructions.md # The system prompt
āāā tools/ # defineTool() tools
āāā skills/ # Instructions loaded on demand
Loading a folder runs its code, so only load ones you trust. See Agent directories.
Features
- MCP: connect to MCP servers, or serve your agent as one. MCP
- Multi-agent: sub-agents that run in parallel, and handoffs to specialists.
- UI: bindings for React, Vue and Svelte, plus AI SDK
useChatand Next.js routes. - Tracing: OpenTelemetry GenAI spans and a local trace viewer. Observability
- Lousho Studio: a separate install (
npx lousho-studio) opens a local visual canvas, run debugger and chat across all your projects. Lousho Studio - Self-healing (experimental):
lousho improveturns an agent's failed runs into tested edits to its instructions and skills, applies one that passes (or queues it for a person), and rolls it back on a regression. Self-healing - Workspaces (experimental):
lousho/workspacesholds the contracts for a workspace of pages, harnesses and shared policy: schemas, validation, harness composition and typed authoring operations. Workspaces - Coding agents: workspace tools, permission rules and starter kits from
lousho add. Build a coding agent
Documentation
The full guides are at lousho.com, in English and Arabic. Good places to start: Quick Start, Tools, Providers, CLI and Troubleshooting.
Coding agents can read the docs from node_modules/lousho/docs, indexed by llms.txt. The repo also has every page in one file, llms-full.txt.
Examples
Most examples run offline with a mock provider. The examples index has the full list and how to run each one. A few to start with:
- ops-pipeline: monitor alert, Slack button, human approval, fixer agent, gated GitHub PR
- coding-harness: a coding agent with checkpoints, permission rules and a loop guard
- deep-research: parallel researcher sub-agents and a cited report
- support-desk: triage handoffs and an approval-gated refund tool
Status
Alpha. The API may change before 1.0. Pin a version. Upgrading covers the breaking changes between alphas and how to move your code.
Community
- Questions and ideas: GitHub Discussions.
- Bugs and feature requests: GitHub issues.
- Arabic docs: lousho.com/ar.
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup and the checks a pull request must pass. To report a vulnerability, see SECURITY.md.
License
MIT Ā© Ali Mohammad
Related Skills
claude-mem
117.7kPersistent Context Across Sessions for Every Agent ā Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu ā one CLI, zero API fees.
Understand-Anything
92.9kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9kš The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit ā see the Safety scan above for what the skill file itself contains.
