SkillAgentSearch skills...

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/lousho

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
šŸ”Œ

MCP Server

Model Context Protocol server

Quality Score

73/100

Supported Platforms

Claude Code
Claude Desktop

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.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
4/20
Freshness
15/15

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.

SkillScoreStarsUpdatedFormat
lousho (this skill)by LinuxDevil73101d agoMCP Server
claude-memby thedotmack100117.7ktodayCLAUDE.md
Agent-Reachby Panniantong100112.4k9d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.9k1d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.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.
<div align="center"> <a href="https://lousho.com"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/lousho-dark.svg"> <img alt="Lousho logo" src=".github/assets/lousho.svg" height="80"> </picture> </a>

Lousho — TypeScript AI agent SDK

npm CI Docs License: MIT Node GitHub stars

</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>

Lousho demo: scaffold a project, replay an eval offline, change the prompt, and see the replay flag it

Why Lousho

  • Test agents in CI without an API key. lousho eval records 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 needsApproval pauses 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 build targets 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() and fromAiSdkTools() 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 useChat and 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 improve turns 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/workspaces holds 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

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

View on GitHub
GitHub Stars10
CategoryAI
Updated1d ago
Forks0

Languages

TypeScript

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info
lousho — MCP Server: Install & Safety Check | SkillAgent