Sandbox
Sign in
@yusifeng/formax
Other#Coding#Code review#Testing

Terminal and web AI assistant for software engineering

Formax is an open-source assistant app that works in the terminal and in a web GUI. It is inspired by Claude Code and is meant for software engineering tasks like planning, code changes, and review.

194 stars•7 forks•TypeScript•Updated 1mo ago
Who it's for

Builders who want a Claude Code-style assistant in the terminal and browser.

What it delivers

You can run an AI assistant inside your project to plan work, make edits, and review changes.

What it does

Terminal workflow

Start the assistant from a project directory with `formax` and work in a terminal-first flow.

Setup flow

Use `formax setup` to enter credentials and runtime config before using the app.

Web and desktop GUI

Open the UI with `formax web`, with Electron desktop support and browser mode.

App-server mode

Run `formax app-server` to provide a JSON-RPC backend for GUI and IDE clients.

WebSocket bridge

Run `formax serve` for the WebSocket bridge used in advanced debugging or split deployments.

How to get it

  1. 1Run
    npm i -g @yusifeng/formax@beta
  2. 2Start in your project directory
    cd /path/to/your/project
formax
  3. 3On first run, Formax will prompt for missing credentials and runtime config. If you want…
    formax setup

README

Formax

English | 简体中文

Formax is an open-source implementation of a Claude Code-style AI assistant for software engineering tasks, with both TUI and GUI workflows.

It is inspired by (but not affiliated with) Claude Code v2.0.67. Some behaviors are implemented by observation (for example, network traces) rather than upstream source code.

The project is currently in Beta and is better suited for learning, experimentation, and architecture study than stable production daily use.

CI codecov npm node license

More demos (click to expand)

Plan mode

/init（create CLAUDE.md）

Sub-agent and code review

Install

npm i -g @yusifeng/formax@beta

Quickstart

Start in your project directory:

cd /path/to/your/project
formax

On first run, Formax will prompt for missing credentials and runtime config.
If you want to run the guided setup first:

formax setup

Default config directory: ~/.formax/

GUI

formax web

Notes for formax web:

  • formax web requires setup credentials first. If missing, the command exits and asks you to run formax setup in terminal.
  • The Threads header always shows an Add project button.
  • In desktop clients (Electron), it opens a native folder picker and starts a thread in the selected project.
  • In browser-only mode, folder picking is not available; hovering the button shows Desktop only.

Advanced Modes (Optional)

formax app-server

Provides a JSON-RPC backend for GUI/IDE clients.

formax serve

Starts only the WebSocket bridge (typically for advanced debugging or split deployments).

More

Docs index: docs/index.md
Code navigation: CODEMAP.md

Current Gaps

  • Claude Code hooks support is still incomplete and under active development.
  • Tool execution behavior is not guaranteed to be fully identical to Claude Code. WebFetch and WebSearch currently have known stability and behavior gaps, and MCP is not supported in this version.
  • Formax Web is still relatively minimal today. The current UI direction is intentionally modeled after Codex.

Maintainer Notes

  • You will see .codex/skills, docs/, and plans/ in this repo. They can feel noisy, but they are intentionally kept as traces of AI-assisted development.
  • This project is built 100% with Codex. If you want to implement your own features, opening the repo in Codex gives useful context from those artifacts.
  • If there are features you want, please mention them in a PR. Ongoing Claude Code compatibility research may be prioritized first in upcoming iterations.

Safety & Limitations

Formax is experimental. Always review proposed commands and file changes before approval. You are responsible for modifications made in your environment.

At this stage, the project is better suited for learning, reverse-engineering, and experimentation than for stable production workflows.

Provider support status:

Anthropic and OpenAI-compatible paths are available in setup/runtime flows. Gemini is present in config surfaces but not fully supported in runtime execution yet.

License

MIT (see LICENSE).

Files in the repo

Repository payload•23 top-level entries
  • .codex
  • .github
  • .vscode
  • bin
  • claude-research-docs
  • docs
  • example-gifs
  • packages
  • plans
  • scripts
  • .gitignore
  • AGENTS.md
  • ARCHITECTURE.md
  • bun.lock
  • CLAUDE.md
  • CODEMAP.md
  • knip.json
  • LICENSE
  • package.json
  • README.md
  • README.zh-CN.md
  • tsconfig.json
  • vitest.config.ts

Discussion (0)

Ask about usage, or say what you built with it

Sign in to join the discussion.

No comments yet. Be the first to say what this is good for.

More other

nexu-io/open-designOther

🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images & video — real files, HTML/PDF/PPTX/MP4 export. 🤖 Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode & 20+ CLIs via BYOK.

95k
tinyhumansai/
openhuman
tinyhumansai/openhumanOther

OpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.

40k
agentscope-ai/QwenPawOther

Your Personal AI Assistant; easy to install, deploy on your own machine or on the cloud; supports multiple chat apps with easily extensible capabilities.

35k
sindresorhus/awesomeOther

😎 Awesome lists about all kinds of interesting topics [NOTE: Pull requests are temporarily disabled until I have a chance to catch up with the existing ones]

505k
aipoch/open-scienceOther

AIPOCH Open-Science is an open-source, local-first, model-agnostic AI research workbench for macOS, Windows, and Linux, with scientific agents, Python/R notebooks, data connectors, and reproducible provenance.

4k