HyperChat 2.0: a config-file-driven local agent platform, shipped as alpha
HyperChat is a Chat client that strives for openness, utilizing APIs from various LLMs to achieve the best Chat experience, as well as implementing productivity tools through the MCP protocol.
At a glance
- What is it?
- HyperChat is a TypeScript chat client and local agent platform that stores agents, MCP tool servers and memory in a .hyperchat/ directory inside your project. It ships two front ends (a web workspace manager and an agent-first CLI), and its current line is published as 2.0.0-alpha releases.
- Who is it for?
- Adopt HyperChat if you want agent definitions, MCP server wiring and chat history to live in a .hyperchat/ directory you can commit and move between machines, and if you are comfortable running alpha builds from the dev2 branch. Skip it if you need a stable release line or a hosted service with an SLA.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem HyperChat targets: agents that live in a project, not in a vendor account
Most chat clients keep your prompts, your agent definitions and your tool wiring on someone else's server. HyperChat's README frames the opposite arrangement: a local AI agent platform where all AI capability is configured through files, so it can be version controlled and moved with the project. The README states the goal as making every project have its own dedicated AI brain, with a complete .hyperchat/ configuration directory that travels with the repository.
The intended user is a developer or a small team that already pays for model access through one or more providers and wants a single local client in front of them. The README lists openai, claude, gemini, kimi and qwen as provider values for HyperChat_AI_Provider, so the client is positioned as a router over existing API keys rather than a subscription product. A second audience is automation: the CLI is described as suitable for scripts, command line workflows and CI/CD integration, which is a different job from a chat window.
There is a real tension in that positioning. A personal chat client and a CI/CD automation tool have different failure requirements. A chat window that drops a connection is an annoyance. A test-runner agent invoked from a pipeline that silently picks the wrong MCP server is a broken build. The README presents both use cases as supported by the same core, and the architecture section is where you have to look to judge whether that holds.
Two front ends over one core: workspace manager versus agent-first CLI
The 2.0 architecture is split into a web layer and a CLI layer. The web layer is built around a WorkspaceManager that caches multiple workspace instances, each with its own MCP client pool. The README's code sketch shows the access path as workspaceManager.get(workspacePath), then workspace.getMcpManager(), then mcpManager.getClient(clientName). Tools are therefore shared across every agent in that workspace, and the web UI keeps multiple workspaces open as tabs with independent agent sets, MCP services and chat history, pushed over SSE.
The CLI layer inverts that. The sketch shows workspace.getAgentInstance(agentName) and then agentInstance.getMCPClient(clientName), with an explicit note that it falls back to the workspace-shared MCP if needed. The stated benefit is that workspace initialization is skipped and the agent starts directly, loading its built-in tools before reaching for shared resources. Practically, this means an agent can carry its own tool configuration and still borrow the workspace pool, which is what makes `hyperchat agent mybot "..."` usable in a pipeline without a full workspace bootstrap.
The repository layout in the README reflects this split: packages/shared for types, packages/core with src/cli, src/workspace (including workspaceManager-enhanced.mts), src/mcp and src/commands, plus packages/web as the React layer. If you are evaluating the project, that layout is the honest map of where complexity sits. The workspace manager is the load-bearing component, and the README does not describe what happens when two processes open the same workspace concurrently.
Installing and running it: the commands the README actually gives
Installation is a global npm package or a one-shot run. The README gives `npm install -g @dadigua/hyperchat` and the alternative `npx -y @dadigua/hyperchat`. The binary is `hyperchat`.
For a first chat, the README sets four environment variables and then passes a prompt as an argument: HyperChat_API_KEY, HyperChat_API_URL, HyperChat_AI_Provider (documented values include openai, claude, gemini, kimi and qwen) and HyperChat_AI_Model. With those exported, `hyperchat "hello"` uses the default model.
The web mode is `hyperchat serve`, which the README says listens on http://localhost:16100, adjustable through HYPERCHAT_PORT, with HYPERCHAT_HOST for the bind address and HYPERCHAT_WEB_PASSWORD for access control. Note that the password is an environment variable or a CLI flag (`hyperchat serve --password=clipass`); the README does not describe user accounts or per-user permissions, so treat the web UI as a single-operator surface unless you find otherwise in the source.
The agent workflow is where the CLI differs from a normal client. `hyperchat agent list` discovers agents globally and in the current workspace. `hyperchat agent mybot "hello"` starts one directly. `hyperchat agent mybot chat` opens an interactive session. `hyperchat agent create mybot` and `hyperchat agent delete mybot` manage definitions, and `hyperchat workspace create` initialises a workspace in the current directory. Two newer features are worth noting because they change how you type: multiple @ references in one prompt (`hyperchat "compare @./package.json and @./yarn.lock"`), and agent custom commands driven by Markdown templates, invoked as `hyperchat agent coder "/bug-fix @./src/login.ts"`. The second feature means your prompt library is a set of files, which fits the project's config-as-code stance.
Configuration resolution is a five-layer stack, lowest to highest: built-in defaults, process.env, a global .env at ~/Documents/HyperChat/.env, a workspace .env, then CLI arguments. The README also documents provider-specific overrides such as HYPERCHAT_OPENAI_BASE_URL and HYPERCHAT_CLAUDE_BASE_URL, plus HYPERCHAT_LANGUAGE (zh or en) and HYPERCHAT_LOG_LEVEL. The layer order is the part to internalise: a workspace .env silently overrides your shell exports, which is convenient for per-project keys and confusing the first time a stale file wins.
Where the design shows strain
The honest limitation is release status. The most recent releases listed are v2.0.0-alpha.63 and v2.0.0-alpha.62 from August 2025, with the last stable tag being v1.8.4 from June 2025. The default branch is dev2. The README itself says HyperChat 1.0 was hand-written and is being migrated to 2.0, and that 2.0 is developed with AI coding tools. That is a candid statement, and it also tells you the 2.0 line is a moving target. If you need a version that does not change under you, the alpha channel is the wrong place to be.
A second constraint is the licence. The repository metadata reports NOASSERTION, which means GitHub could not match the licence file to a known identifier. The README does not state licence terms. For a tool that stores API keys in a .env inside your repository, the licence question is not academic: you need to know whether redistribution or internal commercial use is permitted before you standardise on it. Read the licence file in the repository rather than trusting a badge.
A third issue is that the README's architecture claims outrun its operational detail. The five-layer environment system is documented precisely. The MCP lifecycle is not. There is no description in the supplied material of how MCP servers are declared in the .hyperchat/ directory, how their processes are started or stopped, or what a failed server does to an agent invocation. The README shows the accessor methods (getMcpManager, getMCPClient) but not the config schema behind them. That gap matters most for the CI/CD use case, where a silently missing tool turns into a wrong answer rather than a visible error.
Finally, the web UI is a local server with a single password. The README documents HYPERCHAT_HOST, so binding to a non-loopback address is possible, and that is the configuration to think hardest about before exposing it on a shared network.
How this differs from a terminal coding agent such as Claude Code
The closest comparison in the material is the AI coding tool the README says 2.0 is developed with. A terminal coding agent of that kind is typically bound to one vendor's models and one session in one repository, with tool access mediated by that vendor's harness. HyperChat takes the opposite approach on both axes: the provider is a configuration value (openai, claude, gemini, kimi, qwen), and the tool layer is MCP, an open protocol, rather than a fixed built-in toolset.
That difference has consequences. With a single-vendor agent, the tool surface and the model are tested together, so behaviour is more predictable. With HyperChat, you assemble the combination: your provider, your model name, your MCP servers, your agent's Markdown command templates. The README's custom command example (`/bug-fix`, `/review`, `/optimize`) is exactly this kind of assembly, and it is also exactly the kind of thing that breaks quietly when a template references a file path that moved.
The other difference is persistence. HyperChat's pitch is that the agent definition, its memory and its chat history are files in .hyperchat/ that travel with the repository and can be reviewed in a pull request. That is a genuine contrast with session state held in a hosted account, and it is the strongest argument for the project. It is also the argument that depends most on documentation the README does not yet provide: the file format of an agent definition, and what a memory file looks like when it is committed.
Maintenance cost and what the alpha channel implies
Two release streams are visible. v1.8.4 is the stable tag from June 2025. The 2.0.0-alpha series runs through August 2025 with alphas landing days apart, which is a normal cadence for active development and a poor fit for anyone who wants to pin a version and forget it. The README points readers to an archive/README.1.md for 1.0 documentation, confirming that the documentation itself is split across versions.
Upgrade cost is dominated by the config surface. The five-layer environment system means an upgrade can change which layer wins without you editing anything, and the CLI's agent-first path depends on the workspace manager's fallback behaviour, which is described in prose but not specified. If you adopt HyperChat, treat the .hyperchat/ directory as the artefact under version control and pin the package version explicitly rather than tracking latest, because the alpha tags move.
On licensing, the only accurate statement is that the repository metadata reports NOASSERTION and the README does not state terms. That is a fact about the material, not a legal conclusion. If you plan to use HyperChat inside a company or redistribute it, resolve the licence file before you build on it.
Editorial conclusion
Adopt HyperChat if you want agent definitions, MCP server wiring and chat history to live in a .hyperchat/ directory you can commit and move between machines, and if you are comfortable running alpha builds from the dev2 branch. Skip it if you need a stable release line or a hosted service with an SLA. Before committing, verify three things yourself: what the repository's licence file actually grants (the metadata reports NOASSERTION, so read the file rather than the badge), whether the MCP servers you depend on are reachable from the CLI's agent-first path, and whether the 1.8.4 line or the 2.0.0-alpha line is the one your team will pin.
Community notes