code-mode

Code Mode & Remote Development Environments

The Code conversation mode turns Ariadne into a full coding assistant with direct access to real files, terminals, and development tools — not just a chat interface that generates code snippets for you to copy. The agent can read, write, search, and run code against an actual working environment on your behalf.

How Code Mode Works

When you start a Code conversation, Ariadne's orchestrator automatically looks for a connected client (Desktop app, Console instance, or Docker container) and requests the full set of development tools that client has available. From that point on, the agent can use those tools seamlessly during the conversation — checking out a codebase, running tests, editing files, and iterating — all without you having to leave the chat.

The Remote Tool Request Flow

You type a message
       │
       ▼
EventResponder detects Code conversation
       │
       ▼
Publishes agent.tools_request.{conversationId}
       │
       ▼
Connected client(s) respond with their tool list
       │
       ▼
Tools are registered for this conversation
       │
       ▼
Agent calls tools → EventResponder routes to
agent.tool_request.{conversationId}.{toolName}
       │
       ▼
Client executes locally, returns result
       │
       ▼
Agent sees result, continues reasoning

This all happens transparently. You just ask "add error handling to the database module" and watch the agent read the file, reason about it, and write the changes.

Available Development Tools

Whichever client is connected, the agent gains access to these core tools from the shared Ariadne.LocalTools library:

File Operations

Search & Navigation

Execution

With exec_program and terminal, the agent can run your build system, test suite, linter, package manager, REPL, or any other CLI tool available on the host.

Language Server Protocol (LSP)

When LSP support is configured, the agent also gains code-intelligence tools that go beyond text search:

• Go to definition — find where a symbol is defined
• Find references — find all usages of a symbol
• Hover information — get type and documentation for any expression
• Diagnostics — query compiler errors and warnings in real time

This allows the agent to reason about code structure accurately even in large, multi-file projects.

Working Environments

You can connect to Ariadne from several different environments for Code mode. Each option has different trade-offs for isolation, persistence, and convenience.

Option 1: Ariadne Desktop App (Windows)

The Desktop app is the most seamless option for working on your local machine. When the Desktop app is running and you open a Code conversation in the web UI (or in the Desktop app itself), it automatically connects and advertises its local tool set.

What the agent can access:

• Your full local Windows filesystem (the working directory is your configured project folder)
• Any program installed on your machine — Git, dotnet, node, python, cargo, etc.
• Named terminal sessions that persist across turns within the conversation

Best for:

• Working on a project already checked out on your Windows machine
• Using tools that require Windows-specific dependencies
• Getting the Desktop's Computer Use capability alongside code assistance (the agent can see your screen and edit files)

How to connect:

1. Open the Ariadne Desktop app and sign in
2. Open or create a Code conversation in either the Desktop app or the web UI
3. The Desktop app connects automatically — no additional configuration needed

The Desktop app uses FileSystemToolManager for code tools and DesktopChatToolManager for UI/visual tools. In Code mode, both tool sets are available.

Option 2: Local Console Instance

The Console app runs on any OS and connects to Ariadne via NATS or WebSocket. Running a local Console instance is a lightweight way to give the agent access to your current machine's filesystem without the full Desktop UI.

What the agent can access:

• Files relative to the Console's working directory (defaults to the directory you launched it from)
• Any program in your system PATH or specifiable by full path
• Persistent bash and terminal sessions on your machine

How to connect:

# Connect to a specific Code conversation on your Ariadne instance
dotnet run --project Ariadne.Console -- \
  --conversation-id code-myproject \
  --user "Your Name" \
  --headless \
  --nats-url nats://your-ariadne-host:4222

Or with WebSocket transport (for remote Ariadne instances):

dotnet run --project Ariadne.Console -- \
  --conversation-id code-myproject \
  --user "Your Name" \
  --headless \
  --service-url https://your-ariadne-instance.com \
  --token <your-api-token>

Once running, open that conversation in the web UI — the agent will use the tools from your local machine.

Best for:

• Working on macOS or Linux (the Desktop app is Windows-only)
• Targeting a specific project directory without changing your Desktop configuration
• Quick, disposable sessions where you don't need the full Desktop UI

Option 3: Docker Console Container

Running the Console as a Docker container gives the agent a fully isolated, reproducible development environment. This is ideal for building projects that need specific toolchains, avoiding "works on my machine" problems, or letting the agent work autonomously in the background.

How it works:

The Console container runs in headless mode with a persistent volume mounted at /app/work. The agent's file operations are scoped to this directory. Any development tools you install in the container image are available to the agent via exec_program.

Docker Compose configuration (from the default stack):

devenv:
  image: ariadne-console:latest
  environment:
    ARIADNE_CONVERSATION_ID: "headless-ariadne-dev"
    ARIADNE_HEADLESS: "true"
    NATS__Url: "nats://nats:4222"
  volumes:
    - devenv_data:/app/work    # Persistent working directory
  networks:
    - ariadnenetwork

The ARIADNE_CONVERSATION_ID must contain the word headless for the EventResponder to recognise it as a remote-tool-capable session and automatically request client tools when that conversation is used.

What the agent can access:

• The /app/work volume — persists across container restarts
• All tools installed in the container image (Git, build tools, language runtimes)
• Persistent terminal sessions within the container

Starting an ad-hoc container:

docker run -it --rm \
  -e ARIADNE_CONVERSATION_ID=headless-dev-session \
  -e ARIADNE_HEADLESS=true \
  -e NATS__Url=nats://your-nats-host:4222 \
  -v /path/to/project:/app/work \
  ariadne-console:latest

Then open the headless-dev-session conversation in the web UI to interact with the agent using your project files.

Best for:

• Isolated, clean build environments
• Running the agent autonomously overnight (the container keeps running)
• Projects that require specific Linux toolchains
• CI/CD-adjacent workflows where you want reproducible environments

Option 4: Blob Storage Working Directory

For files stored in Ariadne's blob storage (SFTP-backed), the agent can read, search, and reference them without any locally connected client. Blob-stored files are accessible when:

• You have attached large files to a conversation (they are automatically indexed for chunk-based search)
• A previous Console or Desktop session wrote outputs to blob storage
• You explicitly upload files via the web UI

What the agent can do with blobs:

• Search indexed blob content semantically
• Read specific chunks of large files
• Reference previously generated artefacts

Limitation: Blob storage does not support running code. For execution, you need one of the three client options above (Desktop, local Console, or Docker container).

Choosing the Right Environment

Multiple Clients Connected Simultaneously

You can have multiple clients connected to the same Code conversation at once — for example, the Desktop app running on your Windows machine and a Docker container with a Linux build environment. Ariadne will aggregate the tools from all connected clients and present them all to the agent.

The agent can then:

• Read a file from the Desktop (Windows) filesystem
• Build and test it inside the Docker container (Linux)
• Report results back to you in the conversation

This enables powerful multi-environment workflows without any manual file copying.

Tips for Code Mode

• Name your conversation clearly — e.g. headless-myproject-backend makes it easy to identify which container or Console session is connected
• Keep the Console or Desktop running while you work — if the client disconnects, the agent loses access to local tools and will fall back to knowledge-only responses
• Use named terminal sessions for stateful work — e.g. keep a pytest session open so the agent can re-run specific tests without reloading the environment each turn
• Start with "read the codebase" — ask the agent to explore the project structure first before making changes, so it builds an accurate mental model
• Use the Docker container for risky operations — if you're asking the agent to refactor broadly or run unfamiliar scripts, doing so in an isolated container protects your local machine