yusifeng/formax

English | 简体中文

Formax는 소프트웨어 엔지니어링 작업을 위한 Claude Code 스타일의 AI 어시스턴트를 TUI(Text User Interface) 및 GUI(Graphical User Interface) 워크플로우로 모두 지원하는 오픈 소스 구현체입니다.

이 프로젝트는 Claude Code v2.0.67에서 영감을 받았으나(해당 프로젝트와 관련은 없음), 일부 동작은 업스트림 소스 코드(upstream source code)가 아닌 관찰(예: 네트워크 트레이스)을 통해 구현되었습니다.

현재 프로젝트는 베타(Beta) 단계이며, 안정적인 운영 환경에서의 일상적인 사용보다는 학습, 실험 및 아키텍처 연구에 더 적합합니다.

npm i -g @yusifeng/formax@beta

프로젝트 디렉토리에서 시작하세요:

cd /path/to/your/project
formax

처음 실행 시, Formax는 누락된 자격 증명(credentials)과 런타임 설정(runtime config)을 요청합니다.

가이드 설정을 먼저 실행하고 싶다면:

formax setup

기본 설정 디렉토리: ~/.formax/

formax web

formax web 사용 시 참고 사항:

• formax web을 실행하려면 먼저 설정된 자격 증명이 필요합니다. 자격 증명이 없으면 명령이 종료되며 터미널에서 formax setup을 실행하도록 요청합니다.
• Threads 헤더에는 항상 Add project 버튼이 표시됩니다.
• 데스크톱 클라이언트(Electron)에서는 네이티브 폴더 선택기(folder picker)를 열고 선택된 프로젝트에서 스레드(thread)를 시작합니다.
• 브라우저 전용 모드에서는 폴더 선택을 사용할 수 없으며, 버튼에 마우스를 올리면 Desktop only라고 표시됩니다.

formax app-server

GUI/IDE 클라이언트를 위한 JSON-RPC 백엔드를 제공합니다.

formax serve

WebSocket 브리지(WebSocket bridge)만 시작합니다(일반적으로 고급 디버깅 또는 분리된 배포를 위함).

문서 인덱스: docs/index.md

코드 탐색: CODEMAP.md

• Claude Code 훅(hooks) 지원은 아직 불완전하며 활발히 개발 중입니다.

• 도구 실행(Tool execution) 동작이 Claude Code와 완전히 동일함이 보장되지 않습니다.

• WebFetch 및 WebSearch는 현재 안정성 및 동작 측면에서 알려진 격차가 있으며, 이 버전에서는 MCP를 지원하지 않습니다.

• Formax Web은 현재 상대적으로 최소한의 기능만 갖추고 있습니다. 현재 UI 방향은 의도적으로 Codex를 모델로 삼고 있습니다.

• .codex/skills, docs/, plans/ 디렉토리를 볼 수 있습니다.

이 저장소(repo)에 있는 것들입니다. 다소 소란스럽게 느껴질 수 있지만, 이는 AI 지원 개발 (AI-assisted development)의 흔적으로서 의도적으로 유지된 것입니다.

• 이 프로젝트는 100% Codex로 구축되었습니다. 직접 기능을 구현하고 싶다면, Codex로 저장소를 열어 해당 아티팩트 (artifacts)로부터 유용한 컨텍스트 (context)를 얻을 수 있습니다.
• 원하는 기능이 있다면 PR (Pull Request)을 통해 언급해 주세요. 향후 반복 주기 (iterations)에서는 진행 중인 Claude Code 호환성 연구가 우선적으로 처리될 수 있습니다.

Formax는 실험적입니다. 제안된 명령과 파일 변경 사항을 승인하기 전에 항상 검토하십시오. 귀하의 환경에서 이루어지는 수정 사항에 대한 책임은 귀하에게 있습니다.

현 단계에서 이 프로젝트는 안정적인 프로덕션 워크플로 (production workflows)보다는 학습, 역공학 (reverse-engineering), 그리고 실험에 더 적합합니다.

제공자 (Provider) 지원 상태:

설정/런타임 (setup/runtime) 흐름에서 Anthropic 및 OpenAI 호환 경로를 사용할 수 있습니다. Gemini는 설정 인터페이스 (config surfaces)에는 존재하지만, 아직 런타임 실행 (runtime execution)에서는 완전히 지원되지 않습니다.

MIT (LICENSE 참조).