One chat. More ways to get work done.
A web-based AI agent with a focused chat experience, streaming responses, and a provider-ready backend.
Ask OCode.js is an AI-agent web application built around a simple idea: make it easy to talk to an AI, stream its response, and connect the experience to different model providers. The repository includes a React/Vite frontend and a Node.js backend with chat API routes and provider routing.
Project status: Active development. Configure the required provider credentials before expecting AI responses in a deployed environment.
- Highlights
- Technology
- Getting started
- Configuration
- API
- Deploying
- Project layout
- Development checks
- Security
- Contributing
- License
The workspace is evolving toward a prompt-first full-stack builder. The current frontend provides a prompt-first chat entry, starter prompts, provider selection, a local draft plan, and response/error states. A successful chat response is not proof that application files were generated, previewed, committed, or deployed. Visual editing, isolated generated-app previews, GitHub write-back, and OCode.js deployment must not be advertised as available until their integrations are implemented and tested.
- Builder architecture and UI specification: docs/XBO-OCODEJS-BUILDER.md
- Chat streaming — the Gemini chat endpoint can stream incremental response events using Server-Sent Events (SSE).
- Provider-ready architecture — routing includes OpenAI, Claude, Gemini, Qwen, Hunyuan Hy4, OHMABA, and the local
zskprovider; availability depends on each provider's implementation and server-side configuration. - Hunyuan Hy4 — optional OpenAI-compatible Tencent TokenHub adapter, configured with a server-side API key.
- Conductor mode — dispatches review, security, performance, and architecture tasks concurrently across configured providers, with bounded concurrency and partial-failure reporting. The product UI continues to display only Agents; its default route uses Conductor.
- HTTP chat API — accepts chat prompts and can return either a JSON response or a streaming response.
- Modern web stack — React 18, Vite, and Node.js/Express.
- Self-hosting options — run the web client and API locally, or configure the repository for a supported hosting environment.
- Configurable model selection — environment variables and request parameters determine which provider/model is used.
| Layer | Technologies |
|---|---|
| Web client | React, Vite, TypeScript |
| API server | Node.js, Express |
| AI integration | Google GenAI SDK, OpenAI-compatible SDK, provider adapters |
| Realtime / streaming | Server-Sent Events (SSE), Socket.IO/WebSocket components |
| Agent orchestration | Specialist task planner, bounded parallel executor, Conductor report |
| Testing and quality | Vitest, ESLint, Prettier |
| Deployment configuration | Vercel configuration included |
- Node.js 18 or newer
- npm
- An API key for the AI provider you plan to use
git clone https://github.com/zskbot/ask-ocodejs.git
cd ask-ocodejs
npm installCreate a local .env file. Use placeholders only; never paste real API keys into source control.
# Gemini credentials (required when using the Gemini runtime)
GEMINI_API_KEY=your_gemini_api_key
# Optional alias accepted by the runtime
LLM_API_KEY=
# Default provider/model alias: gemini, hunyuan, conductor, or another configured provider
DEFAULT_MODEL=gemini
# Tencent Hunyuan TokenHub (optional)
HUNYUAN_API_KEY=your_tokenhub_api_key
# Explicitly opt in before exposing billable Hy4 calls through the public chat API
HUNYUAN_ENABLE_PUBLIC_API=false
HUNYUAN_BASE_URL=https://tokenhub-intl.tencentcloudmaas.com/v1
HUNYUAN_MODEL=hy4
# Conductor parallel worker limit (1–8; default 4)
AGENT_MAX_CONCURRENCY=4
# Optional custom/self-hosted agent endpoint
OHMABA_URL=
OHMABA_API_KEY=The Gemini runtime uses LLM_API_KEY first, then GEMINI_API_KEY. The default Gemini model is gemini-2.5-flash; set GEMINI_MODEL to override it.
Hunyuan uses Tencent TokenHub's OpenAI-compatible Chat Completions API. The default model is hy4; set HUNYUAN_MODEL or HUNYUAN_BASE_URL only when using a different TokenHub region or compatible endpoint. The Hunyuan API key is read only by the backend. Direct public API access to Hy4 is disabled unless HUNYUAN_ENABLE_PUBLIC_API=true; enable it only after reviewing authentication, quotas, and cost exposure. Conductor includes Hy4 only when this opt-in is enabled.
Open two terminal sessions from the repository root.
Terminal A — API server
npm run apiTerminal B — frontend
npm run devVite prints the local development URL when it starts. Keep the API process running while testing features that call the backend.
| Variable | Purpose |
|---|---|
GEMINI_API_KEY |
Gemini API key used by the Gemini runtime |
LLM_API_KEY |
Optional preferred Gemini key name; takes precedence in the Gemini runtime |
GEMINI_MODEL |
Optional Gemini model override |
HUNYUAN_API_KEY |
Tencent TokenHub API key; backend only |
HUNYUAN_ENABLE_PUBLIC_API |
Must be true to expose Hy4 through the public chat API; defaults to disabled |
HUNYUAN_BASE_URL |
OpenAI-compatible TokenHub base URL; defaults to the Tencent international endpoint |
HUNYUAN_MODEL |
Hunyuan model ID; defaults to hy4 |
AGENT_MAX_CONCURRENCY |
Maximum parallel Conductor workers, clamped to 1–8 |
DEFAULT_MODEL |
Default provider alias, including hunyuan or conductor |
OHMABA_URL |
Optional custom or self-hosted agent endpoint |
OHMABA_API_KEY |
Optional bearer token for the custom endpoint |
PORT |
API server port; defaults to 3000 |
Only configure the variables needed by your chosen provider. Do not commit .env, credentials, access tokens, or deployment secrets.
The Vercel API handler accepts JSON with either message or prompt. The optional model field can select a configured provider, including hunyuan or conductor.
Request
{
"message": "Review this application architecture",
"model": "conductor",
"stream": false
}Non-streaming response
{
"success": true,
"response": "…",
"model": "conductor"
}Set "stream": true or send an Accept: text/event-stream header to request SSE streaming for the Gemini path. Events include delta for incremental text, done when complete, and error if streaming fails.
Conductor mode runs the review, security, performance, and architecture specialists concurrently. It returns a Markdown report and does not edit files, execute shell commands, commit changes, or deploy. See docs/CONDUCTOR-AGENTS.md.
The API validates empty prompts and rejects messages longer than 12,000 characters. The Express server also exposes GET /health and chat routes under /v1/chat.
API behavior can differ by provider. Check the relevant provider implementation before relying on provider-specific streaming or response formats. The current Hunyuan adapter accepts text prompts; image/file payload support is not yet wired into the chat request schema.
The repository includes a vercel.json configuration for the static frontend and API functions.
- Import
zskbot/ask-ocodejsinto your hosting provider. - Configure the required provider environment variables in the provider's project settings.
- Run a preview/staging deployment first.
- Verify the chat API, provider credentials, and streaming behavior before promoting any release.
Do not put secrets in vercel.json, frontend variables, README examples, or committed source files. Never run a production deployment until the preview has been checked and explicitly approved.
The repository includes a multi-stage Dockerfile for the Express API and CI security image scans. It builds the frontend as a validation step, installs production dependencies, runs as the non-root node user, and exposes port 3000. This container is optional and does not replace the Vercel deployment configuration.
docker build -t ask-ocodejs-api .
docker run --rm -p 3000:3000 --env-file .env ask-ocodejs-apiAsk OCode.js/
├── api/ # Serverless API handlers
├── src/
│ ├── agent/ # Agent runtime and system prompt
│ ├── config/ # Provider/model configuration
│ ├── providers/ # Provider adapters, including Hunyuan
│ ├── router/ # Provider selection and orchestration routing
│ ├── orchestrator/ # Conductor specialist coordination
│ ├── executor/ # Bounded parallel task executor
│ ├── workflow/ # Existing full workflow
│ ├── tools/ # Agent tools
│ └── ... # UI, shared utilities, and other modules
├── tests/ # Provider and orchestration tests
├── docs/ # Product and agent architecture notes
├── assets/ # README and project assets
├── wiki/ # Project notes and wiki
├── index.html
├── package.json
├── vercel.json
└── vite.config.ts
npm run build
npm test
npm run lintThese commands are available in package.json. Run them after making changes and resolve failures before opening a pull request.
- Keep API keys and tokens in local environment files or hosting-provider secret settings.
- Rotate a credential immediately if it has been exposed in a commit, log, screenshot, or public issue.
- Validate and review agent tools carefully before enabling them in an environment with access to important files or services.
- Conductor's current specialist workers perform analysis only; they do not have shell or repository write access.
- Do not assume a provider is configured merely because its name appears in the routing layer.
- Create a feature branch.
- Make a focused change and add or update tests where appropriate.
- Run the development checks.
- Open a pull request with a concise description and verification notes.
This repository identifies its license as Apache-2.0. See LICENSE for the full terms.