Zenoide Docs

Zenoide is a Vibe Coding IDE — a browser-based development environment where you work together with an AI to write, fix, and understand code.

Instead of writing every line of code yourself, you describe what you want in plain language and the AI helps you build it. You stay in control — you review what the AI does, approve changes, and guide the direction.

There are two main ways to work with AI in Zenoide:

• Chat — like texting with a very smart developer. You ask questions, the AI answers. It never touches your files — it only talks.
• Agent — like hiring an intern who can actually open files, write code, run commands, and report back. You give it a task, it works autonomously and shows you everything it does.

Zenoide is especially useful for:

• Developers who want to move faster with AI assistance
• Teams who need an audit trail of every AI action
• Developers integrating Zenoide into their own workflows via API

Zenoide is available as a desktop app for Windows and macOS. No technical setup required — download, install, and start coding with AI in minutes.

Step 1 — Download Zenoide

Go to zenoide.app/download and download the installer for your operating system.

Step 2 — Install the app

• Windows: run the .exe installer and follow the wizard.
• macOS: open the .dmg file and drag Zenoide to your Applications folder.

Step 3 — Sign in

Open Zenoide. Click Sign in and use your CodeFoundex account. If you don't have one yet, click Create account — it's free to get started.

Step 4 — Open or clone a project

From the Dashboard, click Open Project to open an existing folder, or Clone Repository to clone a Git repo from GitHub or any other host.

Step 5 — Start working

You're in. Use the Chat panel to ask questions about your code, or launch an Agent task to implement something autonomously.

This section walks you through the main workflows in Zenoide step by step.

Opening a project

1. After signing in, you see the Dashboard.
2. Click Open Project.
3. Type the full path to a folder on your computer (for example /path/to/your/project).
4. Click Open — Zenoide loads the file tree and you are in the IDE.

Your first chat

1. The Chat panel is on the right side of the screen.
2. Type a question about your code, for example: "What does the LoginForm component do?"
3. Press Enter or click the send button.
4. Claude reads your open file and responds.

Tips for better chat results

• Mention specific files with @ — e.g. @LoginForm.tsx — to include them as context.
• Select code in the editor before asking — it is included automatically.
• Be specific: "Why does this useEffect run twice?" beats "Why is it broken?".

Your first agent task

1. Click the Agent icon in the left sidebar (or press Ctrl+Shift+A).
2. Type a task description, e.g. add validation to LoginForm (email format, password min 8 chars).
3. Click Start.
4. Watch the Timeline — every file read and change is visible.
5. When the agent proposes a patch, approve or reject it.

Tips for better agent results

• Be specific: file names, functions, expected behavior.
• Add a .zenoide-rules file for conventions.
• Break large tasks into smaller steps.

Reading the Timeline

The Timeline shows agent steps, chat, and patches. Filter: All | Agent | Chat | Patches.

Managing chat sessions

• Click + in Chat for a new conversation.
• Use the dropdown to switch sessions.
• Click × to close a session (it stays in the database).

The Chat panel sends your messages to Claude with workspace context.

Every message includes:

• The active file you have open
• Any files you @mentioned
• Any text selected in the editor
• The last few messages for context

Chat sessions are persisted in PostgreSQL (chat_sessions, chat_messages). Refresh restores your last active session.

The Agent uses Plan → Tool → Execute → Observe → Decide:

1. Plan — Claude plans from your task.
2. Tool — picks the next tool (read file, run command, etc.).
3. Execute — the tool runs.
4. Observe — Claude reads the output.
5. Decide — next step or done.

When to use Chat vs Agent

Plan in Chat, then hand off to the Agent in one click. If Claude detects file changes are needed, it adds a marker; Zenoide shows ▶ Avvia Agent with involved files.

1. Describe what to build or fix in Chat.
2. Claude responds with a plan.
3. Hidden marker when changes need files.
4. ▶ Avvia Agent appears below the message.
5. Click — Agent starts with full chat context.

You: "Add a loading spinner to LoginForm while submitting."

Claude: Plan with isLoading, submit disabled, spinner — files LoginForm.tsx, maybe Spinner.tsx.

[src/components/LoginForm.tsx] [src/components/ui/Spinner.tsx]
▶ Avvia Agent

From the Dashboard, click Open Project and enter the full path to your project folder.

Navigating files

• Click any file in the tree to open it in the editor.
• Right-click: New File, New Folder, Rename, Delete.
• The tree respects .gitignore.

@-mentions

Type @ in Chat to pick files; their full content is included as context.

Import graph

Zenoide builds a dependency graph; when you mention a file, the agent also gets direct imports for better refactors.

From the UI

1. File → Clone Repository (or Dashboard).
2. Repository URL, e.g. https://github.com/user/myproject.git
3. Destination folder, e.g. C:\Users\davide\Projects
4. Clone — server runs git clone and opens the workspace.

Create .zenoide-rules at the project root. The agent reads it before planning.

# .zenoide-rules

- Always use TypeScript strict mode
- Prefer named exports over default exports
- Use Tailwind CSS for styling, never inline styles
- Write Vitest tests for every new utility function
- Follow conventional commits: feat|fix|chore|docs|refactor
- Never use any type in TypeScript

Think of it as first-day instructions for a new teammate.

The Timeline is a live feed of workspace activity, updated via SSE (server push without refresh).

Events persist in timeline_events. On reload, the last 200 load then SSE resumes — history is not lost after restarts.

MCP (Model Context Protocol) lets models use external tools — like plugins.

1. Preferences → MCP Tools → Add Server
2. Name, SSE URL, description

Popular servers

• GitHub, Linear, Jira, Slack, web search, database

Multiple agent tasks in parallel; in orchestrator mode a primary agent spawns sub-agents for independent work.

1. Task spans independent parts (e.g. frontend + backend auth).
2. Primary agent splits parallelizable subtasks.
3. Sub-agents run; orchestrator merges results.
4. Summary in the Timeline; parent-child links show who did what.

Control Zenoide from the terminal (scripting, CI/CD).

export ZENOIDE_BASE_URL=http://localhost:3000
export ZENOIDE_API_KEY=your_api_key_here

zenoide agent "Add unit tests for the auth module"

--workspace    Path to workspace root
--autonomous   No approval (fully automatic)
--timeout      Seconds (default 300)

zenoide patch --file src/components/Button.tsx --patch changes.diff
zenoide status --task-id abc123-def456

Status: planning, running, completed, error, cancelled.

Profile dropdown (bottom-left) → Preferences, or Ctrl+,.

Appearance

Dark / Light — preference is saved.

AI Model

• claude-opus-4 — most capable, slower
• claude-sonnet-4 — balanced (recommended)
• claude-haiku-4 — fastest

Token quota

• Permissive — works past quota (dev)
• Strict — blocks when exceeded (prod/cost)

MCP Tools: add/edit servers; effective on new agent tasks.

Key variables for local/self-hosted setup:

For programmatic use — integrate Zenoide into tools, scripts, or CI/CD.

An API lets programs talk over HTTP; responses are usually JSON.

Base URL

http://localhost:3000   (development)
https://your-domain.com (production)

Authentication

Every request needs auth: session cookie (browser sign-in) or header

X-API-Key: your_key_here

Chat API

Streams Claude's reply in real time.

Request body

{
  "messages": [
    { "role": "user", "content": "What does the LoginForm component do?" }
  ],
  "modelId": "claude-sonnet-4-20250514",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "rootPath": "/path/to/your/project",
  "context": {
    "activeFilePath": "src/components/LoginForm.tsx",
    "activeFileContent": "export function LoginForm() { ... }",
    "mentionedFilePaths": ["src/lib/auth.ts"]
  }
}

Response

data: {"text": "The LoginForm component "}
data: {"text": "handles user authentication..."}
data: [DONE]

Response

{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "LoginForm refactor",
      "is_active": true,
      "message_count": 12,
      "created_at": "2025-03-18T10:00:00Z",
      "closed_at": null
    }
  ]
}

Request body

{ "workspaceId": "my-workspace-id" }

Response

{ "sessionId": "772a0622-g4bd-63f6-c938-668877662222" }

Agent API

Request body

{
  "taskDescription": "Add input validation to LoginForm",
  "rootPath": "/path/to/your/project",
  "workspaceId": "my-workspace-id",
  "autonomousMode": false,
  "chatSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "mentionedFiles": ["src/components/LoginForm.tsx"],
  "seedInstructions": "Focus on handleSubmit"
}

Response

{ "taskId": "task-abc123", "requestId": "req-xyz789" }

Workspace API

Timeline API

HTTP status codes

Recommended: Fly.io

flyctl auth login
flyctl apps create zenoide
flyctl secrets set \
  DATABASE_URL="postgresql://user:pass@host:5432/zenoide" \
  AUTH_SECRET="your-random-secret-string" \
  ANTHROPIC_API_KEY="sk-ant-your-key"
flyctl deploy

DB migrations (production)

psql $DATABASE_URL < database/init.sql
psql $DATABASE_URL < database/add_agent_steps.sql
psql $DATABASE_URL < database/add_chat_tables.sql
psql $DATABASE_URL < database/alter_timeline_events.sql

• CSP headers, HSTS, restrictive CORS
• /api-docs dev-only in production

Current: v0.1.0 (Sprint 5)

Planned

• Real-time collaboration
• Git diff viewer (inline)
• PR integration from agent tasks
• Voice input
• Mobile app for tasks
• SSO / SAML