ZhikunCode: a self-hosted coding agent you drive from a browser

One server, a browser tab, and a long task

The repository description is an open source enhancement of Codex, Claude Code and Cursor, focused on getting long, complicated tasks done from a single sentence, across education, programming, office work, life, entertainment and games. The tagline in the README is that you deploy it once and then drive the whole process from a browser.

The deployment target is the distinguishing feature. A team installs the system on a server, and then people open a browser and work with it, including from a phone. The README's own framing is that the data does not leave your machine, and that the project is MIT licensed with no vendor lock-in.

The interface is deliberately dual. There is a CLI and a web UI, and the README's table of contents lists the CLI tools, the skill system, the plugin system, the visualisation, the memory system and a competitor comparison as separate sections, so those are the axes the project wants to be judged on.

The scope of the tasks is worth taking seriously. The case study section describes a single continuous five hour and twenty nine minute session in which a model produced a playable browser based 5 versus 5 game with no backend and no external network dependencies, and a separate case in which the same system delivered a single file HTML of one thousand and sixty one lines for a train ticket waiting list visualisation, against a Next.js project from a competing tool that took twenty seven minutes and fifty two seconds.

The audience is a team that wants a coding agent on its own hardware, with a browser reachable from anywhere the team is, and with the option of pointing it at domestic model endpoints.

The primary language in the repository is Java, and there is a single tagged release, v1.0.0, titled Initial Release, dated 2026-04-21, with the last push to the repository on 2026-10-19.

Three runtimes, and the reason for each

The architecture is described in one line in the README: a Java Agent Runtime, a React browser control surface, a Python Capability Service, and panorama visualisation.

The Docker comment in the repository makes the deployment model explicit: a single container, with Java managing Python as a subprocess. That is a decision worth understanding, because it is the reason there are three languages rather than one.

The Java side is the agent runtime, and it is the largest part of the code. The README publishes a historical snapshot of the tracked product source, explicitly labelled as not the current version, at commit ea0170c on 2026-08-09: 134,826 lines across 863 files, of which Java is 93,118 lines in 622 files, React is 33,642 lines in 209 files, and the Python services and CLI are 8,066 lines in 32 files, excluding locally ignored files.

Those ratios explain the shape. The agent runtime, the orchestration, the long-running task management and the memory system are in Java, which gives a mature concurrency story and a static type system for the part of the system that has to stay correct while a model does something unpredictable. The browser surface is React, because it is a browser surface. The Python service is where the tooling lives, and Python has the ecosystem for the kind of capability work an agent needs.

The repository layout matches. There is a backend directory for the Java service, a frontend directory for the React application, a python-service directory, plus configuration, a workspace directory, a tools directory, a scripts directory and a docs directory, along with a .zhikun directory that appears to hold per-project state, and a workspace directory that looks like the sandbox area the agent operates in.

It is a large surface for a project with one release tag, and that is the main thing to weigh about the architecture. Nothing here is a small system.

Model providers, and the configuration surface they imply

The environment configuration is where this project differs most from an upstream assistant, and the .env.example file is the clearest document.

There is a per-provider API key and a per-provider model list, and the providers are DashScope for the Qwen series, a DashScope Token Plan variant with its own key that the file notes is independent of the pay-per-use key and not to be mixed with it, DeepSeek, Moonshot for the Kimi models, a separate Kimi Code subscription key, Zhipu for the GLM models, and MiniMax.

The compose file wires the same variables through, with a default of qwen3.8-max,qwen3.8-flash,deepseek-v4.1-flash,bailian/glm-5.3 for the DashScope token plan models and deepseek-flash for the DeepSeek models, and the key names carry the LLM_PROVIDER_ prefix throughout. The result is a system where the model backend is configuration rather than a hard-coded SDK call, and where a team can switch provider in the front end without redeploying.

There is also an ASR_CORRECTIONS setting, and the comment next to it explains the mechanism in detail. It holds hotword correction rules for speech recognition, in the format standard spelling followed by variant spellings, separated by semicolons, and it describes a two layer approach: the standard spelling is injected into the system entity vocabulary for the ASR model, and the variants are replaced back to the standard spelling in the recognition result. The example list is the product's own name in several mis-transcribed forms.

That is a small feature and it is a revealing one. It says the project is used with voice input in Chinese, where the model name is a name nobody's speech recogniser knows, and it fixes the problem at both ends of the pipeline rather than in the prompt.

The .env.example also carries the comment that all values are optional and are only there to override the defaults the setup would otherwise collect, and it tells you to copy it to .env.

The SWE-bench number, and what the badge does not tell you

The README leads its badges with a SWE-bench Lite result, and it is worth reading precisely.

The technical report covers a submission under the namespace 20260525_zhikuncode, evaluated with the official harness, and the resolve rate is stated as 168 out of 300, which is 56.0 percent, with a patch generation rate of 284 out of 300, which is 94.7 percent.

The two numbers together are the interesting part. Nearly every task produced a patch, and 56 percent of them were judged as resolving the issue. That gap is the normal shape of agent results on that benchmark, and it is worth noting because the patch generation rate is the number that looks impressive on its own and the resolve rate is the one that measures whether the work was correct.

The badge is on the README and the full report is published on the project's GitHub Pages site, and the report link is separate from the code, which means the evaluation is reproducible rather than merely asserted.

The repository also carries a CI badge pointing at a ci.yml workflow, a Docker Ready badge, and a code size badge, and the release list has a single v1.0.0 entry. That combination, a benchmark report, a CI badge and one release tag, is the profile of a project that has just finished a first large push rather than one with a long release history.

The licence is MIT, with the LICENSE file at the root of the repository, and the README badge says the same. The project also ships a SECURITY.md, a CONTRIBUTING.md, a CODE_OF_CONDUCT.md and a CHANGELOG.md, which is the standard accompanying set for a project that expects outside contributions to its sandbox and its skill system.

The head to head audits, and how to read a 68.3 against a 68.4

Most of the README is case studies, and they follow a consistent pattern that is worth understanding as a genre rather than as evidence.

The pattern is: take one real task, give it to ZhikunCode and to a competing tool, and score the two outputs on a fixed list of dimensions. The gold monitor audit uses fourteen dimensions including requirement understanding, development interaction, data accuracy, architecture, code quality and user experience, and the README notes that the report keeps both the strengths and the defects of each side. The result is 68.3 for ZhikunCode against 68.4 for Codex, with the explanation that the two are effectively tied.

The train ticket case uses seven dimensions and lands at 8.68 against 8.45. The interesting operational detail there is that ZhikunCode ran on kimi-k3 and, after the model hit an HTTP 429 rate limit, the user switched to GLM-5.2 and continued in the same logical session. That is a genuinely useful thing to read about, because it describes a failure mode of the multi-provider design and a way out of it.

The five hour game case is a case study rather than a comparison, and it comes with the kind of evidence trail that is unusual in a README: 43 screenshots, 5 raw screen recordings, 19 first party files, 7,979 lines of code, and 10 sub-agents that split the work across gameplay, rendering, AI behaviour and level assets.

There is also an office tool comparison across five tools and six consecutive tasks producing 30 fixed deliverables, and a set of 17 AI code review reports from a same-task review across eight tools scored on six dimensions.

The honest reading of all of this is that these are self-produced comparisons with published evidence, not independent verification. The report itself says it is a single fixed sample task chain and should not be extrapolated to the overall capability of each tool. An evaluator should read them for what they show, which is what a given system produced on a given task and how it behaved under a rate limit, and not as a ranking.

Docker, the single container and the build hardening

The deployment is Docker-first, and the compose file is a production file rather than a development one.

The service is built from the repository Dockerfile with the runtime target, published as the image zhikuncode:latest, and the port mapping is ${ZHIKUN_PORT:-8080}:8080, so the default is 8080 and the compose file documents its own usage at the top with docker compose up -d, docker compose logs -f, docker compose down and docker compose up --build.

The Java runtime options are set in the compose file too, with a default of -Xms256m -Xmx1024m --enable-preview, which tells you both the intended heap size and that the code depends on preview language features, an important detail for anyone who expects a stable Java build.

The Dockerfile is a multi-stage build with a frontend stage on node:22-alpine and a backend stage on eclipse-temurin:21-jdk that uses the Maven wrapper, with the final runtime stage being the target the compose file selects. Two details in the build are worth naming because they are unusual. The frontend stage requires NPM_REGISTRY to be an HTTPS URL, and the build fails with a message saying so otherwise, and the backend stage does the same for MAVEN_REPOSITORY_URL, additionally validating that the path contains only characters in an allowed set before rewriting the Maven wrapper properties with sed. Both checks exist to stop a tampered or mistyped mirror URL from being used silently, which is a reasonable defence for a build that fetches its dependencies from a configurable location.

The npm install in the frontend stage runs with --ignore-scripts and --replace-registry-host=always, which stops package lifecycle scripts from executing during install and forces the registry host to be rewritten rather than trusted from a lock file.

Everything else follows the same shape as the rest of the project: an entrypoint script, start.sh and stop.sh for the non-Docker path, a .env.example to copy, a CHANGELOG, a SECURITY policy and the full documentation directory.

Editorial conclusion

Adopt ZhikunCode if you want a coding agent that runs on infrastructure you control, can be reached from a phone through a browser, and talks directly to Chinese model providers without routing through a foreign API gateway. Do not adopt it if you need a mature upstream assistant, since the project is at version 1.0.0 from 2026-04-21 with a large surface built by a small team, and do not read the evaluation reports as independent verification, because the comparisons in the README are the project's own. Verify first which model provider keys you will set in .env, that the Java, React and Python components are all built by the multi-stage Dockerfile rather than run separately, and that the eight layer sandbox and the cross-session memory actually do what your deployment needs, since those are the two claims the documentation asserts most strongly and the case studies exercise least.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zhikunqingtao/zhikuncode on GitHub