HyperChat: a local AI agent platform driven by config files and MCP

The problem HyperChat addresses: agents that live in a project folder, not a vendor account

Most chat clients treat a conversation as a thing you own in someone else's account. HyperChat takes the opposite position. The README describes it as a local AI agent platform where AI capability is configured through files, so it can be moved and version controlled. The unit of work is a workspace: a project directory that carries a .hyperchat configuration directory. Agents, their prompts, their MCP tool bindings and their memory are written there, which means a teammate who clones the repository gets the same agent setup rather than a screenshot of it.

The intended audience is narrow and fairly specific. You need to be comfortable with a terminal, because the CLI is described as the agent-first path and the README's own examples are all shell commands. You need at least one LLM API key, since HyperChat is a client: it calls OpenAI, Claude, Gemini, Kimi, Qwen and other providers through their APIs, and the README does not claim to run models locally. And you need a project that benefits from tool access, because the MCP integration is what turns a chat window into something that can read and write files on your machine.

The claim worth scrutinising is the privacy framing. Data staying local is true of the configuration and the chat history, but every prompt still travels to whichever provider you configured. HyperChat moves the orchestration layer onto your disk, not the inference.

Two front ends over one workspace: the web pool and the agent-first CLI

HyperChat 2.0 is built as a two-layer architecture, and the split is the most interesting design decision in the repository.

The web layer is workspace-centric. The README shows a workspace manager that returns an MCP manager, which in turn returns a named client. MCP servers are pooled at the workspace level, so several browser tabs can share one set of running tool processes, and state is pushed to the interface over SSE. The README calls out multi-workspace tab management, per-tab agent sets and chat history, and a visual configuration surface as the intended use.

The CLI layer inverts that. Instead of initialising a workspace and its shared pool, the CLI resolves an agent instance directly and asks it for an MCP client, falling back to workspace-shared resources only when the agent does not carry its own. The stated benefit is startup speed: no UI rendering, no workspace bootstrap, just the agent and the tools it needs. That is also why the README positions the CLI for scripts and CI/CD, and the web UI for long-running project work.

The trade-off is visible in the repository layout. There is a packages/core with src/cli, src/workspace and src/mcp, plus a separate packages/web. Two entry paths into the same configuration means two code paths to keep consistent, and the README itself notes that HyperChat 1.0 was hand-written while 2.0 is being developed with AI coding tools. That is an honest admission that the 2.0 line is a rewrite in progress.

Configuration resolution is layered, and this is where most first-run confusion will come from. The README describes five levels, from built-in defaults up through process environment, a global .env, a workspace .env, and finally CLI arguments at the top. The .env.example file lists a slightly different chain, naming ~/.hyperchat/.env as the global location and ./.hyperchat/.env as the workspace location. Those two descriptions do not agree, and the README also mentions ~/Documents/HyperChat as the default application data directory. Check which path your install actually reads before you spend time debugging a key that never loads.

Installing HyperChat and running a first agent from the terminal

HyperChat is published to npm as @dadigua/hyperchat. The README gives two ways to start: a global install, or a one-off run through npx. The npx form is the safer first contact because it leaves nothing behind.

npx -y @dadigua/hyperchat

For a persistent install, the README uses the global flag:

npm install -g @dadigua/hyperchat

Before the CLI can answer anything, it needs a provider. The README's quick configuration sets four variables: the API key, the endpoint URL, the provider name and the model. The provider value is a plain string such as openai, claude, gemini, kimi or qwen.

export HyperChat_API_KEY=your-api-key
export HyperChat_API_URL=your-api-url
export HyperChat_AI_Provider=openai
export HyperChat_AI_Model=gpt-4o

With those exported, a first prompt is a single argument. If the variables are wrong, the failure shows up here as an authentication or connection error rather than at install time.

hyperchat "你好，世界！"

The more interesting entry point is the agent. The README shows listing the agents available globally and in the current workspace, then invoking one by name. The agent name in these examples is a placeholder for whatever you created.

hyperchat agent list
hyperchat agent mybot "你好"

Agents can be created and deleted from the CLI, and a workspace is created for the current directory. The README does not document a rollback or undo for either operation, so treat deletion as final until you have checked the .hyperchat directory yourself.

hyperchat agent create mybot
hyperchat workspace create

If you would rather work in a browser, the serve command starts the web interface on port 16100 by default. The README also shows a password flag for that command, and .env.example defines HyperChat_Web_Password with a placeholder value of 123456, which you should not leave in place on a machine other than your own.

hyperchat serve

Where HyperChat gets in the way: alpha versioning, thin docs and a licence you have to read

The release history is the first real limitation. The most recent published release is v2.0.0-alpha.63 from 2025-08-18. The last stable tag is v1.8.4 from 2025-06-18. Everything the README describes as the two-layer architecture, the agent-first CLI, the multi-@ file syntax and the agent custom commands belongs to the 2.0 line, which is published under an alpha version. If you pin to v1.8.4 you get the older, hand-written client and none of the CLI behaviour documented above. If you take the alpha, you accept that the interface can change between alpha tags.

The documentation is uneven in ways that matter operationally. The README does not document rollback for agent or workspace deletion. It does not describe what happens to a running MCP server when a workspace is closed. And as noted, the environment variable precedence is described two different ways in two files in the same repository. None of these are fatal, but each one costs an afternoon when you hit it.

There is also a security boundary worth stating plainly. The README lists deep tool integration through MCP as a feature, with the ability to operate on the local file system. That is the point of the tool, and it is also the risk. An agent with filesystem tools and a prompt that can be influenced by file contents is a different threat model from a chat window. The README does not describe a sandbox, a permission prompt per tool call, or a path allowlist. If you cannot answer where that boundary sits in your setup, do not point it at a directory you care about.

Finally, the repository reports its licence as NOASSERTION. That means the automated licence detection could not classify the LICENSE file. Before you ship anything built on HyperChat, read that file directly. This is not legal advice, and it is not a claim about what the licence says; it is a statement that the metadata does not tell you.

How HyperChat differs from editor-embedded assistants and terminal coding agents

The obvious alternative is an editor-embedded assistant such as GitHub Copilot, which the README itself names as a tool being used to develop HyperChat 2.0. The difference is structural rather than a matter of quality. An editor assistant is bound to the editor process and to that vendor's account and model routing. HyperChat is a separate process that talks to whichever provider you configure, and its agent definitions are files in your repository. If your team standardises on one editor, the embedded assistant is less setup. If you want the same agent behaviour available from a shell script, a CI job and a browser, the editor assistant cannot give you that.

The second comparison is with terminal-based coding agents that read a repository and edit it. Those typically bundle their own tool set and their own model choice. HyperChat's position is that the tool set is yours: MCP servers are configured per workspace or per agent, and the model is a variable you set. The cost is that you assemble the toolchain. There is no curated default set of tools in the README, only the mechanism for attaching them.

A third option is wiring MCP servers directly into an existing client that already speaks the protocol. That is lighter if you only need one agent and one machine. HyperChat earns its place when you need several agents with different tool sets, shared across a workspace, and you want that configuration to travel with the project through Git.

Maintenance cost, upgrade path and what the version numbers imply

The repository is not archived, and the last push was on 2026-08-26. That is recent activity on the default branch dev2, but it does not change the release picture: the newest published tag is still v2.0.0-alpha.63 from 2025-08-18, roughly a year before that push. Development on dev2 and published releases are moving at different speeds, so anyone installing from npm is getting something older than the branch.

Upgrading is where the alpha status has a concrete cost. The repository has a version:sync script and release tooling in package.json, and the package version is 2.0.0-alpha.63, which means each alpha tag can carry breaking changes to the CLI surface or the .hyperchat layout. The README does not publish a migration guide between alpha versions, and the ChangeLog files are present in the repository root but their contents are not part of what can be confirmed here. Treat an upgrade as a change you test in a scratch workspace before applying to one you rely on.

The licence question is the other cost centre. NOASSERTION means the LICENSE file needs to be read by someone on your team before HyperChat goes into anything distributed. For internal use this is usually a short conversation; for a product that bundles or links it, it is not.

Editorial conclusion

Adopt HyperChat if you want agent definitions and MCP tool configuration to live in files next to your code, reviewable in Git, and you are comfortable running an alpha line: the newest published release is v2.0.0-alpha.63 from 2025-08-18, while the last stable tag is v1.8.4 from 2025-06-18. Skip it if you need a documented rollback path or a stable interface for a shared team install; the README does not describe either. Before committing, verify three things yourself: that hyperchat agent list discovers the agents you expect in your workspace, that your MCP servers start under the agent-first CLI path rather than the workspace pool, and that the LICENSE file resolves the NOASSERTION value GitHub reports.

Frequently asked questions

Official sources

1. BigSweetPotatoStudio/HyperChat on GitHub
2. Issues
3. README
4. Releases