Documentation

v2.0.0

Getting Your Access Key

11ku7-ai-nodecoder uses a community-funded access model with two types of keys. On first launch, the application will guide you through authentication:

🌐 Community Key (Free Access)

When the community funding goal is reached, a Community Key is generated and available to everyone for 2 hours. No registration required:

  1. Check api.11ku7-ai.com for an active community key
  2. Copy the key displayed on the dashboard
  3. When 11ku7-ai-nodecoder prompts for authentication, select "Community Key"
  4. Paste the key — you're in! No account needed

Community keys expire after 2 hours. When expired, re-check the dashboard for a new key.

🔑 Contribution Key (30-Day Personal Access)

For extended access, contribute at api.11ku7-ai.com to receive a personal 30-day key. This requires a registered account:

Step 1: Register

  • Visit api.11ku7-ai.com and create an account (username: 5-8 chars, password: 8-32 chars)
  • After registration, you will be shown a 12-word recovery phrase
  • ⚠️ Save this phrase immediately! It is shown only once and cannot be recovered. You need it to reset your password or revoke compromised sessions.

Step 2: Contribute & Get Your Key

  • Log in at the dashboard and make a contribution
  • A 30-day contribution key is generated and linked to your account

Step 3: Login in 11ku7-ai-nodecoder

  • Launch 11ku7-ai-nodecoder — select "Login" at the auth prompt
  • Enter your registered username and password
  • Your device is locked to your account — one active device per login
  • JWT tokens are saved locally and refresh automatically

🔐 If You Forget Your Password or Get Compromised

Use the 12-word recovery phrase you saved during registration:

  • Reset password: Go to api.11ku7-ai.com → "Forgot Password" → enter username + recovery phrase + new password
  • Revoke compromised session: Dashboard → "Revoke Device" → enter recovery phrase to instantly kill the active session from any device
  • Then re-login in 11ku7-ai-nodecoder with your new credentials

Installation

📦 Method 1: Install via npm (Recommended)

Install globally to get CLI commands available system-wide: 

npm install -g 11ku7-ai-nodecoder

Available commands after install:

Command Description
nodecoder Launch the Terminal UI (CLI)
nodecoder-web Launch in headless WebUI mode (browser-only, no TUI)
nodecoder-web --remote WebUI with LAN/remote access enabled
nodecoder-web --remote --tunnel cloudflare WebUI with Cloudflare tunnel for public HTTPS access
nodecoder-web --remote --tunnel tailscale WebUI with Tailscale tunnel for private network access
nodecoder-web --port 8080 WebUI on a custom port
nodecoder-telegram Launch the Telegram bot interface

🔧 Method 2: Run Locally

Clone the repository and run locally — ideal for contributing or customizing: 

git clone https://github.com/dheeraj21/11ku7-ai-nodecoder.git
cd 11ku7-ai-nodecoder
npm install

Windows users: Use the Windows-specific install for terminal support: 

npm run install:windows

Run locally using node directly:

Command Description
node index.js Launch the Terminal UI (CLI)
node headless.js Launch in headless WebUI mode
node headless.js --remote --tunnel cloudflare WebUI with Cloudflare tunnel
node headless.js --remote --tunnel tailscale WebUI with Tailscale tunnel
node telegram.js Launch the Telegram bot interface

Upon first launch, you'll be prompted to accept a disclaimer and then authenticate with your access key (community or contribution). Select a UI theme from 22 options and choose from multiple AI providers including Gemini, OpenAI, Claude, Groq, Grok, OpenRouter, Ollama, or custom endpoints. Configure your API keys in the .env file. The application starts in Agent Mode by default.

Supported Platforms

🪟 Windows 🐧 Linux 🍎 macOS 📱 Termux (Android) 💻 WSL

Note: Requires Node.js 18.0.0 or higher. Windows uses node-pty for native PTY support (installed automatically as an optional dependency). Linux/macOS/Termux uses Python's pty module.

Core Modes

  • Agent Mode (Default): The autonomous AI developer. Plans multi-step operations, executes shell commands, edits files, analyzes code, and self-corrects. Uses intelligent tool selection to accomplish complex goals.
  • Chat Mode (/chat): A general conversational interface where the AI responds without tool use, ideal for open-ended discussions and quick questions.
  • Digest Mode (/digest): Analyzes project directories or files, providing detailed summaries and content previews. Useful for understanding large codebases.

Toggle Features

  • Auto Mode (/auto [on|off]): When enabled, the agent acts autonomously without asking for confirmations, even for potentially dangerous operations. Self-validates and corrects plans automatically.
  • Web Search (/websearch [on|off]): Enables real-time Brave Search integration for up-to-date information.
  • MCP (/mcp [on|off]): Toggle Model Context Protocol integration for extended tool access.
  • GitHub (/github [on|off]): Toggle GitHub integration for repository management.
  • Skills (/skills [on|off]): Toggle agent skill system. Load specialized capabilities from markdown-based skill files on demand.
  • Memory (/memory [on|off]): Toggle persistent agent memory. When enabled, the agent retains context and learnings across sessions.

Commands Reference

Mode Commands

  • /agent: Switch to Agent Mode (Autonomous Developer - Default)
  • /auto [on|off]: Toggle Auto Mode for fully autonomous operation
  • /chat: Switch to Chat Mode (General Conversation)
  • /digest: Toggle Digest Mode or process a path (e.g., /digest ./my_project)

Integration Commands

  • /websearch [on|off]: Toggle Brave Web Search for real-time information
  • /mcp [on|off]: Toggle MCP (Model Context Protocol) integration
  • /github [on|off]: Toggle GitHub integration
  • /skills [on|off]: Toggle agent skill system
  • /memory [on|off]: Toggle persistent agent memory
  • /crp: Select Current Repository (Change Remote Context)

File & Context Commands

  • /browse: Open file browser to attach files (images, PDFs, text files) to your next message
  • /detach: Detach all currently attached files from context
  • /cwd: Open folder browser to choose current working directory

Session & Utility Commands

  • /help: Display a comprehensive list of commands and key bindings
  • /model: Switch between different AI models and providers
  • /session: Open Session Manager to switch, create, or delete sessions
  • /savecon: Save the entire chat conversation to a markdown file
  • /clear: Clear the chat history and memory for the active session
  • /webui: Toggle Web UI on/off (http://localhost:3000)
  • /logout: Logout from the current contribution key session
  • /exit: Exit the application

UI Navigation (Key Bindings)

  • Esc: Disable input focus (switch to folder tree navigation)
  • i: Re-enable input focus
  • c: Focus the chat area for scrolling
  • s: Focus the save conversation button
  • t: Focus terminal input box
  • Tab: Cycle modes (Agent → Chat)
  • Ctrl+Enter (in input): Enter to next line
  • q or Ctrl+C: Exit the application
  • Up/k (in chat): Scroll chat content up
  • Down/j (in chat): Scroll chat content down
  • Enter (in tree): Toggle folder expand/collapse

For detailed information on any command, type /help or ask the AI directly in Agent Mode.

Security & Session Management

11ku7-ai-nodecoder uses a multi-layered security model built on JWT tokens, device locking, and server-side session management. Here's how each layer works and how to regain control if your account is compromised.

🔑 JWT Token Lifecycle

  • Access Token — Expires every 1 hour. Every API call is verified against this token. When it expires, the client automatically re-authenticates.
  • Refresh Token — Matches the remaining lifetime of your contribution key (up to 30 days). Used to issue new access tokens without re-entering credentials.
  • Session Verification — On each API call, the server checks that your session still exists in the database. If the session has been revoked (remotely or via auto-cleanup), the server returns a SESSION_REVOKED code and the client logs out immediately.
  • Device ID Binding — Tokens are bound to a unique device fingerprint (stored in ~/.device_uuid). Using a token from a different device is blocked.

🚪 Three Ways to Logout

If your program is compromised or you need to terminate a session, there are three independent methods:

1. CLI / Telegram /logout

  • Clears device lock on the server
  • Deletes active session identifier from database
  • Removes ACCESS_TOKEN, REFRESH_TOKEN, and ACTIVE_LOGIN_IDENTIFIER from local .env file
  • Returns you to the authentication screen

2. Remote Device Revocation (via Dashboard)

  • Go to api.11ku7-ai.com and log in
  • Click "Revoke Device" and enter your 12-word recovery phrase
  • The server immediately deletes the session and clears the device lock
  • The CLI tool detects SESSION_REVOKED on its next API call and auto-logs out
  • ⚡ This works from any device — you don't need access to the compromised machine

3. Server Auto-Cleanup

  • The server runs a cleanup cycle every 10 seconds
  • Automatically removes sessions for users whose contribution keys have expired
  • No action required — expired sessions are purged automatically

🔐 Forgot Password / Account Recovery

When you register, you receive a 12-word BIP39 mnemonic recovery phrase. This phrase is your master key for account recovery:

  • Reset Password: Visit api.11ku7-ai.com, enter your username, recovery phrase, and new password (8-32 characters)
  • Revoke Compromised Session: Use the same recovery phrase via the dashboard's "Revoke Device" feature to immediately kill an active session
  • ⚠️ Store your recovery phrase securely! It cannot be recovered if lost. It is shown only once during registration.

🛡️ If Your Account Is Compromised

  1. Revoke the active session — Go to api.11ku7-ai.com, log in, and use "Revoke Device" with your recovery phrase. This kills the session instantly.
  2. Reset your password — On the same dashboard, use "Forgot Password" with your recovery phrase to set a new password.
  3. Re-login on your device — Launch 11ku7-ai-nodecoder, log in with your new credentials. A new device lock and session will be created.

Because the JWT access token expires every hour and each API call verifies the session server-side, a revoked session is detected and terminated within minutes — even if the attacker has your tokens.

Web UI & Headless Mode

11ku7-ai-nodecoder includes a full browser-based IDE interface that can run alongside the TUI or in headless mode (no terminal required).

Starting the Web UI

  • Alongside TUI: Type /webui to toggle on, then visit http://localhost:3000
  • Headless Mode (npm install): Run nodecoder-web — no TUI, browser-only
  • Headless Mode (Run locally): Run node headless.js
  • Remote Access: nodecoder-web --remote — enables LAN access
  • With Cloudflare Tunnel: nodecoder-web --remote --tunnel cloudflare — auto-provisions a Cloudflare tunnel for public HTTPS access
  • With Tailscale Tunnel: nodecoder-web --remote --tunnel tailscale — uses Tailscale for private network access
  • Custom Port: nodecoder-web --port 8080 — sets a custom port (default: 3000)

Web UI Features

  • IDE-style layout with collapsible file explorer
  • Monaco editor for viewing and editing files
  • Real-time chat with markdown rendering and syntax highlighting
  • Status bar with all toggle controls (agent mode, web search, GitHub, MCP, skills)
  • CWD picker, session manager, and model switcher modals
  • File upload for attachments (images, PDFs, text files)
  • Mobile-responsive design
  • Gateway token authentication for secure remote connections

Telegram Bot Interface

Access 11ku7-ai-nodecoder from any device with Telegram installed. The bot mirrors the terminal experience with full command support.

Setup

  1. Create a bot via @BotFather on Telegram
  2. Add your bot token and Telegram chat ID to the .env file as TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID
  3. Start the Telegram bot:
    • npm install: nodecoder-telegram
    • Run locally: node telegram.js
  4. The bot connects automatically and you can begin chatting

Telegram Commands

Setup

  • /start — Begin setup wizard
  • /auth — Authenticate
  • /provider — Select AI provider & model
  • /session — Manage sessions
  • /logout — Log out and clear auth

Settings

  • /cwd — Folder browser (or /cwd <path>)
  • /browse — Attach files from CWD
  • /detach — Remove all attachments
  • /auto — Toggle auto-mode
  • /memory — Toggle memory
  • /mode — Toggle agent/chat mode
  • /status — Show status dashboard

Integrations

  • /crp — Clone/select GitHub repo
  • /websearch — Toggle Brave Web Search
  • /skills — Toggle agent skills (on/off/list)
  • /mcp — Toggle MCP servers (on/off/list)

Control

  • /stop — Interrupt agent
  • /shutdown — Stop bot
  • /help — Show help message

Features

  • Inline keyboard buttons for consent/approval prompts
  • File upload and download support (drag-drop)
  • Markdown/HTML formatted messages with syntax highlighting
  • Status bar toggles via interactive buttons
  • Owner-only access with rate limiting

Cross-Platform PTY Terminal

The agent's shell execution uses true pseudo-terminal (PTY) emulation, with platform-specific implementations that provide persistent, interactive terminal sessions.

🐧 Linux / macOS / Termux

  • Uses Python's pty module
  • Spawns bash/zsh via pty.spawn()
  • Full signal forwarding (Ctrl+C → SIGINT)
  • Works natively on Termux (Android)

🪟 Windows

  • Uses node-pty native addon
  • Spawns PowerShell with ConPTY
  • Custom prompt suppression for clean output
  • ANSI escape code stripping

Shared Architecture

  • Persistent sessions: Terminal stays alive across tool calls, preserving env vars and cwd
  • Output buffering: Ring buffer with configurable timeouts and exit code detection
  • Smart cleanup: ANSI sequences stripped before feeding output to AI
  • Timeout protection: 30s default with automatic process interruption

Diff Validation Engine

A multi-pass validation system that catches AI code generation errors before applying changes to your codebase.

  • Structural validation: Checks syntax integrity of generated diffs
  • Holographic analysis: Uses the Holograph engine to validate scope and symbol consistency
  • Match verification: Ensures SEARCH blocks match actual file content
  • Bracket balance: Validates brace/bracket/paren matching in modified code
  • Auto-retry: On validation failure, automatically re-prompts the AI with specific error guidance

Agent Skill System

Extend the agent's capabilities with modular, markdown-based skill files that inject specialized knowledge into the agent's context on demand.

How It Works

  1. Place .md skill files in the skills/ directory
  2. Toggle skills on/off with /skills or via the WebUI skills modal
  3. Enabled skills are injected into the agent's system prompt, providing specialized instructions

Benefits

  • Reduces base context token usage by loading expertise only when needed
  • User-configurable — choose which capabilities to activate per session
  • Hot-reloadable without restarting the application
  • Toggleable from both TUI and WebUI