Banana Code Documentation

2. Getting Started

The first time you run banana, the app runs a setup wizard: you choose a provider, enter credentials, and pick a model (including optional Auto Mode where the app can route each turn to a suitable model).

Supported providers

Use /provider anytime to switch. Supported values match the app: gemini, claude, openai, mistral, openrouter, lmstudio, ollama_cloud, and local ollama (default if something is misconfigured).

• OpenAI: You can use a standard API key, or Sign in with ChatGPT (Codex OAuth). OAuth uses ~/.codex/auth.json after npx -y @openai/codex login.
• Claude: During setup you also choose default prompt-cache duration (5-minute vs 1-hour writes).
• OpenRouter: Paste your key and a model ID; the app can validate that the model advertises tool calling.
• LM Studio: Connect to local models hosted via LM Studio. Expects the server to be running (default http://localhost:1234).
• Ollama (local): Expects http://localhost:11434; /model lists tags from your machine.

Project context

Sessions are saved automatically (titles, provider, model). Use /chats to pick an older session, or start with banana --resume (see CLI section).

3. Operating Modes

“Style” modes change the system instructions and which tools are emphasized. Only one of these is active at a time; the status bar shows PLAN, ASK, or SECURITY when relevant.

• /agent (default) — Full coding agent: files, shell, terminal PTY, etc., subject to permissions and Guard/YOLO.
• /plan — Plan mode: the model is steered to propose a clear plan before large or risky edits.
• /ask — Ask mode: Q&A and investigation. The write_file and patch_file tools are not offered, so the assistant cannot apply edits while in this mode.
• /security — Security mode: steers the model toward finding and helping fix issues in code you own or are allowed to test. Use defensively only.
• /skill-creator — Helps you author SKILL.md skills with YAML frontmatter under the config skills directory.

Return to normal coding with /agent when you are done with a specialized mode.

4. Slash Commands

Commands start with /. Arguments are optional for many commands (omit them to open an interactive menu). The in-app list is always authoritative—type /help in the terminal to print every command the binary you are running exposes.

Beta-gated: /clean requires enabling “/clean command” under /beta. /effort applies to Claude only. OpenRouter model changes use the full OpenRouter setup flow when you run /model without arguments.

5. File Mentions & Images

Mentions are parsed from your message text. The pattern matches @ or @@ followed by a path in quotes or a non-whitespace token.

• Files: @path/to/file.js — text content is read and added to the prompt. Use @"src/my file.ts" when paths contain spaces.
• Images: @@path/to/image.png — double @ attaches an image for multimodal models (commonly Gemini, Claude, OpenAI).
• Paths: ~ expands to your home directory. Relative paths resolve from the current working directory; absolute paths work as-is.

6. Settings & Memory

Open /settings for a checkbox menu. These map directly to the app’s config:

• Auto-feed workspace files — Periodically includes relevant workspace context (respects .bananacodeignore and .gitignore).
• Syntax highlighting for AI output — Waits for the full reply, then renders with highlighting (useMarkedTerminal).
• Surgical file patching — Enables the patch_file tool for targeted edits (on by default unless disabled).
• Token count in status bar — Shows live estimated usage in the footer.
• Global AI memory — Allows save_memory / list_memory / delete_memory tools and /memory. Turn off to stop persistent facts.
• Banana Guard — AI-assisted auto-approval for commands deemed safe; complements manual prompts. Toggle with /guard as well.
• Claude 1-hour prompt cache — Longer-lived Anthropic cache (higher cache-write cost). Also configurable when first setting up Claude.
• UltraMemory — Background summarization of chats (extra API usage; only processes chats created after you enable it). Confirmation is required in the UI.

/memory opens a small menu to view, add, or delete stored facts when global memory is enabled.

7. Beta, MCP & Built-in Tools

/beta

Toggle optional capabilities: DuckDuckGo quick search, DuckDuckGo scrape (HTML lite — the app warns about terms of use before enabling), delegate_task sub-agents, MCP support, and the /clean history compressor. Enabling MCP runs MCP initialization; disabling it cleans up connections.

Model Context Protocol

With MCP enabled, tools from configured MCP servers appear alongside built-in tools so the model can call them like any other function.

What the model can do out of the box

Core tools registered in the app include shell execution, interactive PTY terminal sessions (send input, terminate), reading/writing files, listing directories, regex search across files, HTTP fetch, optional DuckDuckGo helpers, surgical patches, get_banana_docs (embedded help text), activate_skill, and (when beta is on) delegate_task with roles like researcher, coder, reviewer, or generalist.

8. Routing, Cost & Autonomy

Auto Mode (per provider)

When the configured model is auto, a small router model classifies each user turn and picks a concrete model. The router sees roughly the last seven conversation turns for context. OpenRouter and local Ollama do not use this auto-router in-app—you choose a fixed model ID or tag list.

Fast (premium) Claude variants

Selecting a model id ending in -fast trades higher per-token cost for faster generation; the CLI prints an explicit cost warning.

/context

Shows estimated tokens by category (system, chat, tools), message count, and—when the provider supports it—a session cost and prompt-cache savings line.

Permissions: Guard vs YOLO

Banana Guard tries to auto-approve safe commands. YOLO (/yolo or banana --yolo) skips permission prompts entirely—use only when you accept full automation risk.

UltraMemory

Optional background jobs summarize history so long threads stay coherent; expect noticeable extra API usage.

Self-healing workflow

The agent loop sees tool and shell failures in conversation and can iterate—there is no separate “magic” step; it is the normal tool-use loop with error text in context.

9. CLI & API Server

All flags are read from process.argv when the CLI starts.

• banana --resume — Resume the latest saved session (if any).
• banana --resume <uuid> — Resume a specific session id.
• banana --yolo — Start with YOLO mode on (same as toggling /yolo inside the app).
• banana --api [port] — Run the headless REST API. Default port is 3000 if omitted or not numeric.
• banana --api 4000 --host 0.0.0.0 — Listen on a custom host (default API bind is 127.0.0.1).
• banana --api 3000 --expose — Shorthand to bind 0.0.0.0 (all interfaces).
• banana --api 3000 --no-auth — Disables API authentication—only on trusted networks.

On /exit, the app prints a banana --resume <session-id> hint so you can return to the same thread from the shell.

10. 📱 Banana Remote (Android App)

Banana Remote is a companion Android app that lets you monitor your CLI session and approve or deny AI tool calls from your phone — in real time, from anywhere.

What it does

• Streams complete AI responses to your phone as rich Markdown (headings, code blocks, diffs, tables).
• Sends a push notification whenever the agent wants to run a command, write a file, or apply a patch.
• Approve or Deny tool requests with a single tap — from the notification shade or from inside the app.
• Shows a full history of AI messages and tool events (including diffs for file writes and patches).
• The CLI simultaneously displays the local permission prompt, so you can approve from either device.

Pairing the app to your CLI

Run /remotetooling in the CLI and enter the 6-character pairing code shown in the app. The code expires in 5 minutes. After pairing, a UUID is stored in ~/.config/banana-code/config.json so reconnection is automatic on subsequent sessions.

Disconnecting

Run /remotetooling disconnect at any time. This closes the socket, removes the saved UUID from config, and immediately reverts all permission prompts back to normal local CLI behaviour (Allow Once / Allow for Session / Deny).

How the permission flow works with Remote active

When a tool request arrives and Banana Remote is connected:

• The request is immediately sent to your phone as a push notification.
• The CLI simultaneously shows the standard Allow Once / Allow for Session / Deny prompt.
• Whichever responds first wins. If you tap Approve on your phone, the CLI prompt disappears automatically. If you choose an option in the CLI, the notification is dismissed on your phone.

You never need to physically be at your computer to let the AI continue working.

Privacy & Data

When Banana Remote is active, AI messages, tool call details, and code diffs are relayed through the Banana Code relay server at bananacode.sh over TLS. Messages are signed with HMAC-SHA256. See the Privacy Policy for full details.