# Loushang: a Python agent harness that treats method, session and tool policy as runtime objects

> Loushang is an early-stage Python CLI and SDK for coding workflows, with model routing across GPT, Claude, DeepSeek, Qwen, Kimi, GLM and MiniMax, resumable sessions, and project-level extensions. It is a source-install project today, not a packaged product.

**zhnt/loushang** — AI-native agent harness for coding workflows by python: multi-model LLM orchestration, stateful sessions, tool governance,   traceable delivery, and provider routing for GPT, Claude, DeepSeek, Qwen, Kimi, GLM, and MiniMax.

- Repository: https://github.com/zhnt/loushang
- Stars: 1,637 · Forks: 257
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/zhnt-loushang

## The failure Loushang is aimed at: work that cannot be resumed or audited

The README states the problem plainly: agents can plan and act, but complex work breaks down when context is lost, execution cannot be resumed, tools are hard to govern, and results are not verified. That is a familiar list to anyone who has run a coding agent for more than one sitting. The usual failure is not a bad model answer. It is a session that dies mid-task, a tool call nobody can reconstruct afterwards, and a second run that starts from zero because the first one left no durable record.

Loushang's answer is to make the surrounding machinery first-class. In the README's own vocabulary, method is the work contract, session is the durable record, tool is an executable capability under policy, and provider is a concrete endpoint resolved through a model catalog. The intended audience is engineers running multi-step coding work who care about recoverability and traceability more than about a chat window. It is explicitly early: the README says the stable focus is `loushang code` plus the underlying `loushang.ai` SDK, while `loushang work`, `loushang research` and `loushang ppt` are roadmap items to be treated as evolving directions.

## How the harness is put together: kernel, model layer, substrate, surface

The README describes a layered split that maps onto the source tree. Agent is the execution kernel. `ai` is the model access layer. Harness is the cross-product substrate. Coding is the V1 product surface, tui is terminal presentation, and channel is the boundary protocol. The top-level entries back this up: `src/`, `tests/`, `docs/`, `examples/`, `scenarios/`, `spikes/` and `scripts/` sit alongside a `pyproject.toml` that declares six console entry points, including `loushang`, `loushang-tui`, `loushang-hosted`, `loushang-mux` and `loushang-plugin`.

The provider story is concrete rather than abstract. The Makefile defines an `AI_OFFLINE_ENV` target that strips a long list of credential variables before running tests, among them `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `DASHSCOPE_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY` and `ZAI_API_KEY`. That list is the clearest available evidence of which providers the AI layer actually talks to. The `pyproject.toml` dependencies are narrow: `anthropic`, `openai`, `httpx`, `authlib`, `cryptography` on Darwin x86_64, `markdown-it-py`, `pillow`, `pygments`, `packaging` and `wcwidth`. There is no heavyweight agent framework underneath. Sessions, tools and routing are implemented in this repository, which is why the README can describe them as runtime objects rather than as configuration around someone else's loop.

The pytest configuration is worth reading before you judge the project's maturity. It declares markers for `live` provider verification, `requires_host_runtime` for loopback and process capabilities, and a set of TUI contract markers covering PTY/ConPTY conformance, tmux integration and render correctness. A project that names its terminal-backend contract tests separately is treating the TUI as a tested surface, not a demo.

## Installing from source and running a first coding turn

There is no published package to install. The README says the recommended path is to run from source, and the Makefile confirms the shape of that workflow. Clone the repository and create a virtual environment with uv:

```bash
git clone https://github.com/zhnt/loushang.git
cd loushang

uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

The `dev` extra pulls in `pytest`, `pytest-cov`, `ruff`, `mypy` and `types-Pygments`. If you prefer the Makefile, `make bootstrap` does the same thing: the README states it creates `.venv/` with `uv` and installs the project in editable development mode. Note the explicit warning that there is no `make install` target, only `make bootstrap` for development and `make install-binary` for a local binary install. That is an unusual thing to have to document, and it tells you the build tooling is still settling.

Once the environment is active, the README's quick start lists the first commands to run:

```bash
loushang --help
loushang --list-models
loushang --list-commands
loushang -p "Inspect this repository and summarize what it does."
```

`--list-models` is the one to run first, because it is how you find out which providers the catalog resolves given the credentials present in your environment. `--list-commands` shows the command surface, and `-p` runs a single prompt. The README does not state what output `-p` prints or where a session created this way is stored, so treat the first run as a discovery step rather than a scripted one. For anything beyond a single prompt, the README points at `examples/coding/` for CLI, session, tool and extension scenarios, and `examples/ai/` for model lookup, complete, stream, tools and typed contexts. Those directories are the practical documentation; the prose docs live under `docs/en/`.

## Extensions are Python code in your project, which is both the feature and the risk

The README defines an extension as project-level Python code that can contribute hooks, tools, resources, commands and flags. This is the most consequential design decision in the project. It means the harness is not a closed tool surface you configure with YAML; it is a substrate you extend by writing code that runs inside the agent loop.

The upside is that tool governance can be expressed in the same language as the rest of your stack, and a custom tool is a Python callable rather than a plugin manifest in a foreign format. The `loushang-plugin` console script exists for plugin work, and the `examples/` tree has separate `agent`, `harness` and `tui` directories in addition to `coding` and `ai`, which suggests the extension points are exercised across more than one surface.

The risk is that an extension hook is arbitrary code with access to whatever the process has. The README does not describe a sandbox, a permission prompt, or a capability boundary for extension code. Tool governance is described as a policy layer over executable capabilities, but the documentation excerpt does not say how policy is declared or enforced. If you are evaluating Loushang for a team, that gap is the first thing to close by reading `docs/en/concepts/` and the extension examples directly. Until you have, treat third-party extensions the way you would treat any unreviewed dependency that runs in your shell.

## Where Loushang is the wrong choice

Three cases stand out. The first is anyone who needs a stable, versioned interface. The package version is 0.1.0, the README says the project is in early development and recommends running from source, and there are no retrieved releases. If your integration depends on a frozen CLI contract or a published wheel, this is not the tool yet.

The second is anyone who wants a single-provider, single-model workflow. Loushang's value is concentrated in multi-provider routing, session durability, and the extension substrate. If you only ever call one model and you do not need resumable sessions, you are paying the complexity of a provider catalog and a tool policy layer for nothing. A thin client over the provider's own SDK will be easier to reason about.

The third, and the one the README is silent on, is rollback. The README documents resume, fork, export and diagnostics for sessions, but it does not document undoing a completed change or reverting a tool's side effects. If your workflow requires an automatic rollback path, verify that it exists before relying on it. The same silence applies to cost controls: the README mentions cost helpers in `loushang.ai`, but the excerpt does not describe budgets or hard stops, and the roadmap places budgets in V4 alongside team workflows and approvals.

## How it differs from a general agent framework

The obvious comparison is a general-purpose agent framework where you assemble a loop, wire tools, and manage conversation state yourself. The difference in approach is where the state lives. In a framework-style setup, the session is whatever you keep in memory or in your own store, and the tool list is whatever you passed in. In Loushang, session and tool are named runtime objects with operations attached: the README lists resume, fork, export and diagnostics for sessions, and describes tools as capabilities made available under policy.

That shifts the work. You spend less time building persistence and more time learning the harness's model of methods, stages and roles. The README frames a method as a work contract defining roles, phases, workflow, constraints, artifacts and acceptance expectations for a class of work. That is a heavier concept than a system prompt, and it is the part most likely to divide users: if your work fits a repeatable shape, the contract pays off; if every task is ad hoc, the contract is overhead you will end up ignoring.

The project also acknowledges its lineage directly. The README names OpenAI Codex, pi, python-prompt-toolkit, browser-use, Kimi CLI, superpowers, gstack, openclaw and hermes-agent as references and inspiration, and states that unless listed in `THIRD_PARTY_NOTICES.md`, their code is not included or redistributed. That is a more honest acknowledgement section than most, and it tells you the design is a synthesis of patterns rather than a from-scratch architecture.

## Licence, redistribution and the maintenance picture

Loushang is licensed under Apache-2.0, with `pyproject.toml` declaring `license = "Apache-2.0"` and listing `LICENSE`, `NOTICE` and `THIRD_PARTY_NOTICES.md` as licence files. The README adds a redistribution condition worth reading before you ship anything derived from it: when redistributing source, binaries, documents or modified versions, keep `LICENSE` and `NOTICE`, and retain attribution in product documentation, About/Credits pages, or equivalent third-party notices. Third-party dependency information lives in `THIRD_PARTY_NOTICES.md`. This is a summary of what the repository states, not legal advice; if you are redistributing commercially, have counsel read the actual files.

The repository is not archived and the last push was on 2026-09-09, so the codebase is being touched. The README describes the project as in active early development, and the roadmap runs from V1 (`loushang code`) through V5 (a managed runtime for method-bound complex work). Upgrade cost is therefore the real question rather than abandonment risk. Because the recommended install is an editable source checkout, upgrading means pulling and reinstalling rather than bumping a pin, and any extension you wrote against internal hooks is exposed to refactors. The `Makefile`'s `HARNESSTUI_SHARED_SOURCES` list, which enumerates specific files under `src/loushang/harness/` and `src/loushang/tui/` as shared sources, hints at how much internal structure the TUI depends on. Budget for reading diffs, not just for running an upgrade command.

## Conclusion

Adopt Loushang if you are comfortable running a source checkout with uv, want provider routing and resumable sessions in one Python package, and are willing to read the docs tree and examples directories to learn the extension surface. Do not adopt it if you need a packaged binary, a frozen API, or a product where the README already documents rollback, because it does not. Before committing, verify two things: that `loushang --list-models` resolves the providers you actually have credentials for, and that a session you create with `-p` can be resumed and exported in the way your workflow needs.

## FAQ

### How do I install Loushang?

The README recommends running from source: clone the repository, create a virtual environment with uv, and install the project in editable mode with the dev extra. You can also run make bootstrap, which creates .venv/ with uv and installs in editable development mode. There is no make install target.

### Which model providers does Loushang support?

The description lists GPT, Claude, DeepSeek, Qwen, Kimi, GLM and MiniMax, and the Makefile's AI_OFFLINE_ENV target strips credentials for Anthropic, OpenAI, DeepSeek, DashScope, Moonshot, MiniMax and ZAI among others. The README says providers are resolved through a model catalog, and loushang --list-models is the command that shows what resolves in your environment.

### What are Loushang sessions and can they be resumed?

The README describes a session as a durable coding conversation and execution record. It states that sessions can be resumed, forked, exported and inspected, and lists persistent coding sessions with resume, fork, export and diagnostics as available today.

### Is Loushang ready for production use?

The README states the project is in active early development and recommends running from source, and the package version is 0.1.0. The stable focus is loushang code and the loushang.ai SDK, while loushang work, loushang research and loushang ppt are described as roadmap directions.

### What licence does Loushang use?

Loushang is licensed under the Apache License 2.0 unless a file states otherwise, and pyproject.toml declares license = "Apache-2.0" with LICENSE, NOTICE and THIRD_PARTY_NOTICES.md as licence files. The README asks redistributors to keep LICENSE and NOTICE and to retain attribution in product documentation or equivalent third-party notices.

## Sources

- [Issues](https://github.com/zhnt/loushang/issues)
- [License: Apache-2.0](https://github.com/zhnt/loushang/blob/main/LICENSE)
- [README](https://github.com/zhnt/loushang/blob/main/README.md)
- [zhnt/loushang on GitHub](https://github.com/zhnt/loushang)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zhnt-loushang