Loushang: a method-driven agent harness for coding workflows

The failure Loushang is built around: work that cannot be resumed or audited

The README names the problem directly: 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 specific complaint. It is not about model quality. It is about the scaffolding around the model, and it is aimed at developers running long coding tasks where a lost session means starting over.

The intended user is a developer comfortable in a terminal, working on repositories large enough that a single prompt will not finish the job. Loushang's answer is to promote things that are usually implicit into runtime objects: methods, stages, roles, tools, sessions and work products. A method is described as a structured work contract defining roles, phases, workflow, constraints, artifacts and acceptance expectations for a class of work. A session is a durable record that can be resumed, forked, exported and inspected.

That framing has a cost. If you want a quick question answered, a contract with phases and acceptance expectations is overhead you will not recover. Loushang is not competing for that use case, and the README does not pretend otherwise.

How the layers fit: method, session, tool, extension, provider

The README describes the architecture as a set of named layers: method is the work contract, work is the runtime fact, 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 the terminal presentation, and channel is the boundary protocol. Only the first two layers and the ai SDK are described as usable today. The rest are named as organizing concepts.

Concretely, `loushang.ai` is presented as a provider-aware AI SDK with a model registry, streaming, tool calls and cost helpers. A model provider is a concrete endpoint and model resolved through that catalog, which is how routing across GPT, Claude, DeepSeek, Qwen, Kimi, GLM and MiniMax is meant to work. Tools are executable capabilities made available to the agent under policy, which is where the governance claim lives. Extensions are project-level Python code that can contribute hooks, tools, resources, commands and flags.

The data flow implied by this is: a method defines the phases, the session records what happened, the agent kernel calls tools under policy, the ai layer resolves a provider and model, and the tui presents it. What the README does not specify is how a method is authored, whether methods are files, Python objects or something else, and how policy for tool exposure is declared. Those details live in the docs tree, not in the README, so treat the layer diagram as a map rather than a specification.

Getting it running from source, and what the Makefile does not have

The README recommends running from source because the project is in early development. The sequence it gives is:

git clone https://github.com/zhnt/loushang.git cd loushang uv venv .venv source .venv/bin/activate uv pip install -e ".[dev]" loushang --help loushang --list-models loushang --list-commands loushang -p "Inspect this repository and summarize what it does."

The first three `loushang` invocations are the useful ones for evaluation: `--list-models` shows what the catalog resolves to, `--list-commands` shows the command surface, and `-p` runs a single prompt non-interactively. The README also mentions `make bootstrap`, which creates `.venv/` with `uv` and installs in editable development mode, and notes that there is no `make install` target. For a local binary install the target is `make install-binary`.

That last detail matters more than it looks. A Makefile with `bootstrap` and `install-binary` but no `install` tells you the maintainers expect contributors and source checkouts, not packaged distribution. There is no PyPI instruction in the README, and no releases were retrieved for this review, so do not assume `pip install loushang` works. The README also directs local development to the project virtual environment in `.venv/`, which suggests the tool expects to be run from within its own checkout during this stage.

What the README does not tell you about tool governance and verification

Two of the project's headline claims are the least documented in the README. Tool governance appears as "tools are executable capabilities made available to the agent under policy," but the README never says what a policy looks like, whether it is per-session, per-project or per-method, or what happens when a tool call is denied. Traceable delivery appears in the repository description but the README's own list of what you can use today covers the CLI, the AI SDK, sessions, tools, extensions and methods, without describing an artifact trail or how acceptance expectations in a method are checked against actual output.

That is a real gap for anyone evaluating this on the governance angle. You can confirm from the material that sessions are durable and can be exported and inspected, which gives you a record after the fact. You cannot confirm from the README how a tool is constrained before it runs, or what the failure mode is when a method's acceptance expectations are not met. The docs tree has a concepts section and a reference section, so the answers may exist there, but they are not in the material supplied here and I am not going to guess at them.

The honest reading: the method and session machinery is described in enough detail to understand the intent, and the governance machinery is described at the level of a slogan. Verify the second before you build a workflow on it.

Where Loushang is the wrong tool

The clearest limitation is stated by the project itself: Loushang is in active early development, and the broader surfaces (`loushang work`, `loushang research`, `loushang ppt`) are roadmap items that should be treated as evolving product directions. If your requirement is a tool that will not change shape under you, this is not it yet.

There is a second, less obvious boundary. The whole design assumes the work benefits from an explicit contract with phases, roles and acceptance expectations. For exploratory work where you do not yet know what the deliverable is, writing a method first is backwards. You would be encoding a plan before you have one. A plain interactive agent session is the better fit there, and Loushang's own session and resume features do not change that.

A third constraint follows from the multi-provider routing. Resolving models across GPT, Claude, DeepSeek, Qwen, Kimi, GLM and MiniMax means the harness has to normalize tool-calling and streaming behaviour across providers that do not behave identically. The README presents the registry and streaming as existing features of `loushang.ai` but does not claim uniform capability across every model in the catalog. If your workflow depends on a specific tool-calling pattern, check that pattern against the specific model you intend to route to rather than assuming the abstraction flattens the differences.

Compared with a bare agent loop or a single-vendor CLI

The obvious alternative is a single-vendor coding CLI, of the kind Loushang itself lists under acknowledgements: OpenAI Codex, Kimi CLI, and similar tools. The difference in approach is scope of coupling. A single-vendor CLI ties you to one provider's models and one vendor's notion of a session, and typically gives you a chat loop with file editing and command execution. Loushang separates the provider layer (`loushang.ai` with its model registry and cost helpers) from the product surface (`loushang code`), so switching models is a catalog lookup rather than a different tool. Whether that separation holds up in practice depends on how uniformly the providers behave, which is exactly the thing the README does not quantify.

The second alternative is building on a general agent framework and writing your own session persistence and tool policy. Loushang's argument against that is that methods, sessions and tools are first-class runtime objects rather than application code you maintain. The trade is that you inherit Loushang's opinions about what a method is and how phases work, and you take on an early-stage dependency in exchange for not writing the session store yourself. For a team that already has a working internal harness, that trade is probably not worth it. For a team starting from a chat loop and a folder of prompts, the session fork and export features are the part most likely to save time.

Licence, attribution and the cost of tracking an early-stage dependency

Loushang is Apache-2.0 unless a file states otherwise. The README spells out the redistribution obligation: keep `LICENSE` and `NOTICE`, and retain attribution in product documentation, About or Credits pages, or equivalent third-party notices. It also points to `THIRD_PARTY_NOTICES.md` for dependency information and notes that the acknowledged projects (Codex, pi, python-prompt-toolkit, browser-use, Kimi CLI, superpowers, gstack, openclaw, hermes-agent) are references and inspiration, with no code included or redistributed unless listed in that notices file. That is a normal Apache-2.0 arrangement, and the notices file is the thing to read before you ship a fork. This is a description of what the licence text says, not legal advice.

Maintenance cost is the harder question. The repository was last pushed in September 2026 and has no retrieved releases, so there is no versioned artifact to pin and no changelog to read for breaking changes. Running from source with `uv pip install -e ".[dev]"` means upgrades are `git pull` plus a reinstall, and any local extension code you write against project-level hooks is exposed to whatever the hooks API does next. The extension mechanism is the part most likely to churn, because it is the surface third-party code binds to. If you adopt Loushang, budget for reading diffs rather than reading release notes, and keep extensions thin until the hook contract stabilises.

Editorial conclusion

Adopt Loushang if you already think in terms of explicit work contracts and want sessions that can be resumed, forked and exported rather than a chat that resets. Skip it if you need a stable release or a one-command install, because the README itself says to run from source and describes the project as in active early development. Before committing, run `loushang --list-models` and `loushang --list-commands` against your own provider keys, then check whether the method and extension concepts in `docs/en/concepts/` match how your team actually plans work.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. zhnt/loushang on GitHub