Model or dataset
BigSweetPotatoStudio/HyperChat avatar
BigSweetPotatoStudio/HyperChat

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.

708 stars74 forksTypeScriptNOASSERTION

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 3 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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • BigSweetPotatoStudio/HyperChat708 ★ · +1
Star history
Repository2026-09-112026-11-15
BigSweetPotatoStudio/HyperChat707708

1 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial 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. 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 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.

Frequently asked questions

How do you install HyperChat?

The quickstart offers npm install -g @dadigua/hyperchat and npx -y @dadigua/hyperchat, both of which resolve against the npm registry. The root manifest names the same package but marks it private at version 2.0.0-alpha.63, so a local build driven by node scripts/build.mjs may be the working path. The visible documentation is in Chinese.

Where does HyperChat keep its configuration?

Under a .hyperchat/ directory in the project, with mcp.json, ai_models.json, a .env file and an agents/ folder. Each agent directory holds agent.yaml, memory.md and a chatlogs/ folder. The global .env is documented as ~/Documents/HyperChat/.env in the quickstart and as ~/.hyperchat/.env in the shipped example file.

Which port and password does the HyperChat web interface use?

The web UI is reached at http://localhost:16100 after hyperchat serve. The port is written as HYPERCHAT_PORT in the quickstart and as HyperChat_HTTP_PORT in the example file, which also ships HyperChat_Web_Password=123456. The quickstart instead uses HYPERCHAT_WEB_PASSWORD or a --password argument, and HYPERCHAT_HOST sets the bind address.

Which AI providers can HyperChat talk to?

The provider variable HyperChat_AI_Provider is documented with the values openai, claude, gemini, kimi and qwen, and HyperChat_AI_Model carries the model name, shown as gpt-4o in the quickstart and gpt-4 in the example file. HYPERCHAT_OPENAI_BASE_URL points at a custom endpoint. Tools come through the MCP protocol rather than through the model itself.

Is HyperChat still being worked on?

The repository is not archived and its last recorded push is 2026-08-26, on the default branch dev2. The newest release is v2.0.0-alpha.63 from 2025-08-18, and the root manifest still declares that same version, so the branch has moved past the newest published alpha. Version bumps are made with npm version --no-git-tag-version plus a sync script.

Official sources

  1. BigSweetPotatoStudio/HyperChat on GitHub
  2. Issues
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/bigsweetpotatostudio-hyperchat.svg)](https://hysenlabs.com/projects/bigsweetpotatostudio-hyperchat)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/bigsweetpotatostudio-hyperchat.svg)](https://hysenlabs.com/projects/bigsweetpotatostudio-hyperchat)

Was this useful?