Codeon Documentation

Getting Started

Codeon is a desktop application available for macOS, Windows, and Linux. After downloading and installing, launch the app to see the welcome screen.

Opening a Project

Click Open Project to select a folder. Codeon will:

• Load your project files into the sidebar file explorer
• Initialize Git if the folder doesn't already have it (for checkpoint/restore functionality)
• Create a .ai-agent folder to store chat sessions and metadata
• Display recent projects on the welcome screen for quick access

The Main Interface

The Codeon interface consists of:

• Top Bar — Shows the Codeon logo, current file path, and settings button
• Sidebar — File explorer with your project structure (resizable)
• Main Tabs — Code, Agents & Skills, MCP, AET, Learning, and Docs
• Editor Area — Monaco-based code editor with VS Code features
• AI Chat Panel — Right panel for conversing with Claude
• Bottom Panel — Console, Terminal, Problems, and Tasks tabs

Authentication

Codeon uses Claude's Agent SDK which requires authentication with your Anthropic account or API key.

Authentication Methods

Codeon supports multiple authentication methods:

1. Claude OAuth (Recommended)

If you have the Claude CLI installed and authenticated, Codeon will automatically detect your credentials from:

• macOS: macOS Keychain (service: "Claude Code-credentials")
• Windows: Windows Credential Manager
• Linux: ~/.claude/.credentials.json

2. API Key

You can also provide your own Anthropic API key in Settings. This is useful if you want to use your own account's API quota.

3. OpenRouter

Codeon supports OpenRouter as an alternative provider, allowing you to use various AI models through a unified API.

Claude Auth Gate

If you select Claude.ai Login but aren’t signed in yet, Codeon shows an auth gate when you open a project. Click Sign in with Claude.ai and the modal will auto-close once the session is detected.

Onboarding & Provider Setup

Codeon guides you through setup with a welcome screen, recent projects, and a provider selection flow so you can start coding quickly.

Welcome Screen & Recent Projects

When you launch Codeon, the welcome screen lets you open a project and shows a list of recently opened folders for quick access.

• Open Project opens a new workspace and initializes project state
• Recent Projects lets you reopen or remove saved entries

LLM Provider Selection

If a provider isn't configured (or credentials are missing), Codeon will prompt you to choose:

• Claude.ai Login — uses your Claude subscription
• Anthropic API Key — direct API access
• OpenRouter — multi‑model access via OpenRouter

You can change providers anytime in Settings.

Model Loading & Indexing

On first launch and when opening large projects, Codeon may show:

• Model Loading — initializes AI features
• Indexing Overlay — scans files and symbols to improve responses

Code Tab

The Code tab is your primary workspace for writing and editing code with AI assistance.

Monaco Editor

Codeon uses the Monaco Editor (the same editor that powers VS Code) providing:

• Syntax highlighting for 100+ languages
• IntelliSense autocomplete suggestions
• Multi-cursor editing
• Find and replace with regex support
• Code folding
• Minimap for quick navigation

Diff View

When the AI makes changes to a file, Codeon automatically applies and saves the changes, then shows a side-by-side diff view highlighting exactly what was modified. You can:

• Review the original and modified versions side-by-side
• Click Done to dismiss the highlighting for individual files
• Click Done All to dismiss all diff highlights at once
• Use Restore on a message to revert to a checkpoint if needed

AI Chat Panel

The right panel is where you interact with Claude. You can:

• Ask questions about your code
• Request changes — Claude will edit files directly
• Debug issues — paste errors and get solutions
• Generate code — describe what you need
• Attach files — drag and drop or click to attach context

Chat Composer Controls

The composer includes quick controls so you can steer each message:

• Agent mode selector — Plan, Default, Accept Edits, or Bypass per message
• Model selector — switch models for the next prompt
• @ context picker — attach files/folders or select Agents/Skills
• Inline context chips — attached files/folders show above the input with one‑click remove
• Attachment preview — images, files, and code pills appear with remove buttons
• Message queue — if a run is active, messages are queued and can be reordered or sent now

Multi-Chat Sessions

Create multiple chat sessions to organize different tasks. Each session maintains its own:

• Conversation history
• Agent selection
• Attached context

Switch between sessions using the tabs at the top of the chat panel. Click the + button to create a new tab, or right-click tabs to rename or close them.

File Attachments

Add context to your messages by attaching:

• Files — Any file from your project
• Images — Screenshots, diagrams, or UI mockups
• Code selections — Highlight code in the editor and attach it

Tip: If you copy code from the editor and paste it into the chat input, Codeon turns it into a compact code pill (with file + line range) instead of dumping the full snippet into the textbox.

Agents & Skills

Create specialized AI assistants and reusable capabilities to customize Claude's behavior for your workflow.

What are Agents?

Agents are specialized Claude instances with custom instructions. Think of them as role-based personas:

• Security Reviewer — Focus on finding vulnerabilities
• API Designer — Specialize in REST/GraphQL design
• Test Writer — Generate comprehensive test cases
• Documentation Writer — Create clear documentation

Agent Scope

Agents can be stored in two locations:

Creating an Agent

Agents are Markdown files with YAML frontmatter:

---
name: Security Reviewer
description: Reviews code for security vulnerabilities
---

You are a security expert. When reviewing code:
1. Check for SQL injection vulnerabilities
2. Look for XSS attack vectors
3. Verify proper authentication/authorization
4. Flag hardcoded secrets or credentials
5. Identify insecure dependencies

Using Agents

To activate an agent for your chat session:

1. Click the @ button in the chat composer (or type @ in the input)
2. Select Agents from the category menu
3. Choose the agent you want to use — a pill appears above the chat input showing it's active
4. The agent's persona is now active for all messages in this session until changed or removed

To remove an active agent, click the × button on the agent pill.

What are Skills?

Skills are reusable capabilities that Claude can invoke. Unlike agents (which persist for the session), skills apply to the next message only and contain instructions for specific tasks.

Skill Structure

Skills live in directories under .claude/skills/ (project) or ~/.claude/skills/ (user):

.claude/skills/
└── deploy-vercel/
    ├── SKILL.md          # Main instructions
    └── scripts/          # Optional scripts
        └── deploy.sh

Using Skills

To use a skill for your next message:

1. Click the @ button in the chat composer (or type @ in the input)
2. Select Skills from the category menu
3. Choose a skill — a pill appears above the chat input showing it's selected
4. Type your message and send — the skill context is automatically applied
5. After sending, the skill selection resets (skills are single-use per message)

Codeon also shows skill suggestions below the chat input based on your message content. Click a suggestion chip to quickly select that skill.

Skill Scripts

Skills can include executable scripts in a scripts/ subdirectory. To run a skill script:

1. Select a skill in the Assistant Tools popover
2. Choose a script from the Skill scripts dropdown
3. Click Run to execute with permission confirmation

Library Sync & Import/Export

From the Assistant Tools popover you can sync your library with ~/.claude:

• Import agents and skills from your user library
• Export project agents and skills for reuse

MCP Servers

The Model Context Protocol (MCP) allows you to connect external tools and services to Claude, extending its capabilities beyond the built-in tools.

What is MCP?

MCP is a protocol that enables Claude to interact with external systems. Each MCP server provides a set of tools that Claude can invoke to:

• Query databases (Supabase, PostgreSQL)
• Access file systems
• Integrate with APIs (Stripe, GitHub)
• Run custom operations

Adding MCP Servers

In the MCP tab, click Add Server to configure a new connection:

Server Types

Built-in Presets

Codeon includes presets for popular services:

• Supabase — Database queries, authentication, storage
• Filesystem — Extended file operations
• Browser — Web automation and scraping

Server Configuration

Each server configuration includes:

• Name — Identifier for the server
• Command — The executable to run (for STDIO)
• Arguments — Command-line arguments
• Environment Variables — API keys, secrets
• Headers — HTTP headers (for SSE)

Plugins Marketplace

The Plugins tab lets you browse, install, and manage Claude Code plugins from multiple marketplaces.

Marketplace & Installed Views

• Marketplace — discover plugins, search, and filter by category
• Installed — manage plugins in your project and user scopes

Install from Git URL

You can install plugins directly from a Git repository URL and choose whether to install them for the current project or your user library.

Plugin Details

Codeon can render a plugin README inside the UI to help you review usage and configuration before enabling it.

Problems Panel

The Problems panel aggregates diagnostics across your workspace so you can fix issues faster.

• Shows editor diagnostics plus optional project‑wide scans
• Groups errors and warnings by file and severity
• Opens files directly when you click a problem

Agent Execution Timeline (AET)

The Agent Execution Timeline provides full transparency into every action Claude takes, visualized as an interactive timeline.

Why AET?

Unlike black-box AI tools, Codeon shows you exactly what the AI is doing:

• Every file read and write
• Every command executed
• Every tool invocation
• Every decision point

View Modes

AET offers three visualization modes:

Node Types

Each node in the timeline represents an action:

• Read — File or resource read operations
• Write — File modifications
• Bash — Terminal commands executed
• MCP — External tool invocations
• Think — Claude's reasoning steps

Playback Controls

In Graph and Mindmap views, use playback controls to:

• Play — Animate through the execution
• Scrub — Jump to any point in time
• Fit — Auto-zoom to see all nodes

Run Selection

Each chat message creates a new "run" in the timeline. Use the dropdown to switch between runs and compare different executions.

Export

Export any run as an AET bundle for sharing, debugging, or documentation purposes.

AET Map & Pinboard

Switch AET to Map view to see a spatial overview of nodes, tool calls, and checkpoints.

Pinboard

Pin important nodes or files and open the Pinboard to quickly revisit them later. Pins are saved per project.

Learning Mode

Learning Mode is a unique Codeon feature that helps you understand what the AI did and why, turning every coding session into a learning opportunity.

How It Works

When enabled, after each AI run completes, Codeon generates an educational explanation covering:

• Summary — What was accomplished
• Reasoning — Why Claude made specific decisions
• Key Concepts — Technical concepts, algorithms, or patterns used
• Code Highlights — Important code snippets with explanations

Enabling Learning Mode

Toggle Learning Mode in the Learning tab using the Auto-learn switch. When enabled, learning explanations are generated automatically after each AI task.

Learning Sessions

Each learning session is stored and can be revisited later. Browse past sessions to:

• Review concepts you learned
• Reference explanations for similar tasks
• Track your learning progress

Documentation Mode

Documentation Mode keeps your product docs up-to-date automatically after each AI run. It captures new features and updates so your documentation stays aligned with your code as you build.

How It Works

When enabled, Codeon creates a docs entry after an AI task completes and generates a structured update, including:

• Feature title and summary
• Usage steps and expected behavior
• Notes for edge cases or configuration

Enabling Documentation Mode

Open the Docs tab and toggle Auto-doc. New updates will appear in the list after each AI run.

Web Preview

Click Web Preview inside the Docs tab to view the documentation in a clean web-ready format that’s easy to share or publish.

Verification Mode

Verification Mode (Proofed Edits) runs local checks after AI changes so you can trust the result before you merge. It validates edits by executing lint, typecheck, and test commands when available.

How It Works

After an AI run completes, Codeon:

• Detects whether files were modified and verification is meaningful
• Plans safe commands (lint, typecheck, tests) based on your project
• Runs checks and records pass/fail status in a certificate

Enable Auto‑verify

Open the Verification tab and toggle Auto‑verify for the current chat session. Each run will generate a verification card with results and a detailed report.

Review & Rerun

Open any verification entry to view:

• Executed commands and outputs
• Files touched by the AI
• Pass/fail status for each check

You can rerun verification at any time if dependencies or tests change.

Git Checkpoints

Codeon creates automatic Git checkpoints before every AI action, allowing you to safely experiment and restore to any previous state.

How Checkpoints Work

Before sending a message to Claude:

1. Codeon creates a Git commit with the subject [AI-Agent-Checkpoint] <reason>
2. The checkpoint hash is stored with your message
3. A Restore button appears on each user message

Restoring a Checkpoint

Click the Restore button on any message to:

• Reset your working directory to that point in time
• Automatically handle branch state (no detached HEAD)
• Stop any running AI operations

Auto-Init Git

If you open a folder without Git initialized, Codeon will:

• Silently initialize a Git repository
• Create an empty initial commit (doesn't auto-commit your files)
• Enable checkpoint functionality

Git Recovery

If a Git operation (merge, rebase, cherry-pick) needs resolution, Codeon displays a recovery card in the chat to help you continue or abort the operation.

Checkpoint Timeline

If your build includes the Checkpoint Timeline modal, it provides a visual list of recent checkpoints with diffs and one‑click restore.

• Browse recent [AI-Agent-Checkpoint] commits
• Preview changed files and diff stats
• Restore or copy the checkpoint hash

Integrated Terminal

Codeon includes a full-featured terminal powered by xterm.js with PTY (pseudo-terminal) support.

Features

• Full PTY support — Run interactive programs (vim, htop, etc.)
• Multiple sessions — Open multiple terminal tabs
• Theme presets — Codeon Dark, VS Code Dark, One Dark, Dracula, and more
• Resizable — Adjust terminal height as needed
• Copy/paste — Standard clipboard support

Terminal Tabs

Access the terminal in the bottom panel. Click the + button to create new terminal sessions. Each session maintains its own:

• Working directory
• Environment variables
• Command history

AI Terminal Execution

When Claude needs to run commands (like npm install or git status), the output appears in the Console tab. Claude can also suggest commands for you to run in the terminal with your approval.

Console, Tasks & Receipts

The bottom panel includes Console, Tasks, and Receipts to help you track what the AI is doing.

Console

Shows streaming logs, command output, and system messages for each chat session.

Tasks

Displays the AI todo list with counts for pending, in‑progress, and completed items.

Receipts

Every tool invocation can be logged as a receipt. Use search and filters to review tool names, working directories, and network policy context.

Permissions & Safety

Codeon implements workspace isolation and permission gating to keep AI actions safe and scoped to your project.

Permission Modes

Select your preferred level of AI autonomy:

Network Policy

Control what network requests Claude can make:

• Allow All — No restrictions
• Deny All — Block all network access
• Allowlist — Only permit specific domains

Workspace Isolation

Codeon enforces strict boundaries:

• File operations are restricted to your opened project
• Claude cannot access or modify files outside the project
• The Codeon app itself is protected from modification
• Path traversal attempts are blocked

Permission Requests

When Claude needs approval, a permission dialog appears showing:

• What action is requested
• What files/commands are involved
• Options to Allow, Deny, or Allow for this session

Advanced Controls

Pause Before Next Tool

Enable Pause before next tool in AET to step through tool calls safely. When paused, Codeon asks for confirmation before the next tool runs.

File Locks

Lock files from the file explorer or the AET node drawer to prevent edits on sensitive paths. Locked files are skipped during AI edits.

Context Inspector

Open the Context Inspector to view the exact prompt and attachments sent to the model. You can copy the prompt, request id, or full redacted payload.

Ask‑User Questions

When Claude needs clarification, Codeon can show a multi‑choice question modal with an optional free‑text answer.

Updates & Notifications

Codeon includes an in‑app updater and a notification system for announcements.

• Update banner shows when a new version is available
• Release notes modal provides the changelog
• Download progress and install options appear inline

Licensing & Access

Codeon validates your license and trial status to keep access in sync with your account.

License Gate

If your trial expires or a machine needs activation, Codeon shows a license gate with options to sign in, activate, or purchase.

Offline & Entitlement Checks

When offline, Codeon may prompt you to reconnect to verify access. Updates can also require an active entitlement.

Settings

Access settings by clicking the gear icon in the top-right corner.

AI Provider

• Provider — Choose between Claude (Anthropic) or OpenRouter
• API Key — Enter your API key (optional if using OAuth)
• Model — Select which Claude model to use

Agent Mode

Set the default permission mode for AI actions (Plan, Default, Accept Edits, or Bypass).

Network Policy

Configure network access restrictions for AI-initiated requests.

Editor

• Font Size — Adjust code editor font size
• Theme — Monaco editor theme
• Word Wrap — Enable/disable line wrapping

Terminal

• Theme — Select terminal color scheme
• Font Size — Terminal text size
• Shell — Default shell to use

License

View your license status, activate a license key, or purchase a license from within the app.