Documentation - Sci-pilot

Quick Start

Get up and running with Sci-pilot in under 2 minutes.

A Full AI Agent Platform — Not Just a Chatbot

Sci-pilot is a desktop AI agent — not just a chatbot. It can take actions on your computer: execute shell commands, search the web, manage files, run Python/JavaScript code, control Discord, read emails, and more — using 11 built-in MCP servers with 40+ tools. It runs a full agentic loop (up to 25 iterations per request) where it reasons about the problem, picks the right tool, executes it, reads the result, and continues until the task is done. Add persistent memory that grows over time, sub-agent delegation, and 24/7 autonomous mode — and you have a personal AI workforce, not just a text generator.

1

Install Sci-pilot

Download the installer from the waitlist confirmation email and run it.

2

Add an API Key

Go to Settings > Providers and enter your Anthropic or OpenAI API key.

3

Choose Your Model

Go to Settings > Agents and select your preferred provider and model.

4

Start Chatting

Click + New Chat and send your first message. The agent can use tools, search the web, execute code, and more.

Providers

Chat

The Agent Can Configure Itself

You don't have to set up everything manually. Sci-pilot's agent can configure itself — just ask it in natural language. Need a new MCP server? Say "Configure Docker as an MCP server". Want to change your model? Just ask. Need a skill installed? Say "Install the web-search skill". The agent searches, installs, and configures everything automatically — settings, tools, providers, and more.

Example: Agent auto-configuring Docker MCP Agent automatically configuring itself

Teams

Coordinate multiple AI agents working together on complex projects. Teams share a task board and communicate through a mailbox system.

Multi-Agent Collaboration with Shared Task Boards

Some tasks are too complex for a single agent. A software project needs a coder, a reviewer, and a project manager. Teams let you assign specialized agents to roles, give them a shared objective, and let them coordinate autonomously. Each team has a shared task board with task dependencies (Task B waits for Task A), auto-dispatch (tasks assigned automatically when ready), and stale detection (resets tasks if an agent crashes). Agents communicate through a mailbox system with threading support and anti-loop detection. Pre-built templates include Dev Squad, Research Team, Content Pipeline, and DevOps Pipeline.

Dashboard > Teams Teams dashboard

1

Tab Navigation

Switch between Teams, Tasks, and Agents views.

2

Create a Team

Click + New Team to create a team. Assign agents, define goals, and let them collaborate autonomously.

3

Shared Task Board

Each team has a kanban-style task board. Agents claim, update, and complete tasks independently.

4

Team Mailbox

Agents communicate through messages. View the full conversation history between team members.

Create a Team

Create New Team Create new team modal

Choose from pre-built templates (Dev Squad, Research Team, Content Pipeline, DevOps Pipeline) or create a custom team. Assign a name, color, objective, and select teammates from your configured sub-agents.

Team Detail View

Team Detail Team detail with task board and mailbox

The team detail view shows all assigned agents with their roles, a Task Board with task cards (status, priority, assigned agent), and the Mailbox with inter-agent messages. Monitor progress and agent coordination in real-time.

Tasks

Create, assign, and track tasks for your AI agents. Monitor progress with real-time statistics and status filters.

Autonomous Task Execution with Cron Scheduling

Instead of giving your agent one-off requests in chat, Tasks let you organize work into trackable units with real metrics. Create a task, assign it to an agent, and it runs autonomously. Tasks support dependencies (blocked tasks auto-unblock when deps complete), priorities, recurring schedules (cron expressions with timezone), and templates for repetitive work. The Heartbeat system automatically checks for due tasks and executes them — even while you're away. Your dashboard shows completion rate, fail rate, average time, and per-agent performance. It's project management for AI workers.

Dashboard > Tasks Tasks dashboard

1

Statistics Cards

Real-time overview: Total, Pending, In Progress, Completed, Blocked tasks — plus completion Rate, Fail Rate, and Average Time.

2

Status Filters

Filter tasks by status: All, Pending, Running, Blocked, Done, or Failed.

3

Templates & Metrics

Save task templates for recurring work. View detailed metrics and performance analytics.

4

Task Dependencies

Tasks can depend on other tasks. Blocked tasks automatically unblock when dependencies complete.

Agents Monitor

Monitor all your AI agents in real-time. See which agents are active, their status, and live communications.

Intelligent Sub-Agents with Personality & Delegation

An agent is an AI model connected to tools that can reason and act autonomously. Sci-pilot's main agent runs a multi-turn agentic loop with tool-loop detection, structured error recovery, and model fallback chains (if one provider fails, it tries alternatives). It can delegate to specialized sub-agents — each with their own personality (SOUL.md + IDENTITY.md), provider, model, and tool permissions. Sub-agents run in isolated git worktrees for safe parallel coding. The system tracks parent-child relationships with cascade stop (stopping a parent stops all children) and orphan detection (children of crashed parents get re-parented).

Dashboard > Agents Agents monitor

1

Agent Status

See each agent's current state: Idle, Working, or Error. Shows last activity timestamp.

2

Performance Metrics

Track Active, Queue, Spawned, Completed, Failed counts, and total Tool Calls across all agents.

3

Live Agent Feed

Real-time stream of agent communications. See what your agents are doing as they work on delegated tasks.

4

Multi-Agent System

The main agent can spawn sub-agents to handle specific tasks in parallel, each with their own personality and tools.

Providers

Configure your AI provider API keys. Sci-pilot supports 10+ providers — use any model from any provider.

10 LLM Providers with Automatic Fallback Chains

Sci-pilot integrates 10 LLM providers: Anthropic (Claude), OpenAI (GPT-4 + Codex OAuth), Google (Gemini), Groq, Mistral, DeepSeek, xAI (Grok), OpenRouter, Together, and Ollama (local models). Each agent can use a different provider and model. If a provider goes down, fallback chains automatically switch to an alternative. Use Claude Sonnet for complex reasoning, GPT-4.1 for tool-heavy tasks, DeepSeek for cheap routine work, or run local models via Ollama for full privacy. OpenAI supports both API keys and ChatGPT subscription auth (Codex OAuth). You bring your own API keys — Sci-pilot never touches your data.

Settings > Providers Providers settings

1

Supported Providers

Anthropic, OpenAI, Google AI, Vertex AI, Groq, Mistral, DeepSeek, xAI, OpenRouter, Together, and Ollama (local).

2

API Key Management

Enter your API key for each provider. Keys are stored locally on your machine — never sent to our servers.

3

Connection Status

Each provider shows its connection status. Click the info icon for setup instructions and pricing links.

4

Local Models

Run models locally with Ollama. No API key needed — just install Ollama and pull your preferred model.

🔒

Privacy: All API keys are stored locally in config/settings.json. They never leave your machine.

MCP Servers

Extend your agent's capabilities with MCP (Model Context Protocol) servers. Each server provides specialized tools the agent can use.

11 Built-in MCP Servers — 40+ Tools Out of the Box

MCP (Model Context Protocol) is the open standard that gives your agent real-world capabilities. Sci-pilot ships with 11 built-in servers: Shell (execute commands, background processes), Web (search, fetch pages, take screenshots), Code Exec (run Python, JavaScript, Bash in sandboxed environments), Discord (10 tools — manage guilds, channels, messages, threads, roles), GitHub (repos, PRs, issues, code search), Gmail (read, send, search, draft management), YouTube (search, transcripts, analytics), Media (image generation, OCR), Memory (semantic search, persist), Process (system info), and Browser. Servers are hot-reloadable — add or remove capabilities without restarting. Each sub-agent can have filtered MCP access, so your code agent can't send emails.

Settings > MCP Servers MCP Servers settings

1

Built-in Servers

Shell (execute commands), Web (search & fetch), Code Exec (run Python/JS/Bash). Toggle each on/off.

2

Add Custom Servers

Add any MCP-compatible server. Specify the command, arguments, and environment variables.

3

Hot-Reload

Changes take effect immediately — no need to restart. Servers are started and stopped on demand.

4

Community Servers

Browse and install 100+ community MCP servers from the Sci-pilot Hub — one click to add.

Agents Configuration

Configure your primary agent and create specialized sub-agents. Each agent has its own personality, model, and tool permissions.

Per-Agent Personality, Model & Tool Permissions

Every agent in Sci-pilot has its own SOUL.md (personality traits, tone, style), IDENTITY.md (role, expertise, backstory), and tool permissions. The Soul Evolution system analyzes your conversations and automatically refines the agent's personality over time — learning your preferences, communication style, and domain expertise. Create specialized sub-agents: a Data Scientist with Python + analytics tools, a DevOps Engineer with shell + GitHub access, a Content Writer with web search only. Each sub-agent runs in isolated git worktrees for safe parallel coding. The main agent automatically delegates to the right specialist based on the task.

Primary Agent

Settings > Agents > Primary Primary agent configuration

1

Provider & Model

Choose which AI provider and model the agent uses. Switch anytime without losing conversation history.

2

System Prompt Override

Customize the default system prompt. Define how the agent behaves, its tone, and what it should focus on.

3

Personality Files

Define the agent's personality via SOUL.md (core identity), IDENTITY.md (behavior), and USER.md (user preferences).

4

Generation Parameters

Fine-tune temperature, max tokens, and other generation settings for precise control over outputs.

Sub-Agents

Settings > Agents > Sub-Agents Sub-agents list

1

Specialized Agents

Pre-configured agents: Data Scientist, Researcher, Project Manager, Content Creator. Each optimized for their role.

2

Create Custom Agents

Click + New Agent to create agents tailored to your workflow. Define their personality, tools, and model.

💡

Tip: The main agent can automatically delegate tasks to sub-agents. Just ask it to "research this topic" or "analyze this data" and it will choose the right specialist.

Security

Control what your agents can do. Set autonomy levels, restrict directory access, and manage tool permissions.

4-Level Autonomy System with Granular Tool Control

Sci-pilot gives you full control over what your agents can do. Four autonomy levels: Supervised (approve everything), Balanced (auto-approve reads, ask for writes), Autonomous (only high-risk needs approval), and Full/YOLO (no approvals). Beyond that: directory access restrictions (protect sensitive folders), per-tool permissions (Allow / Ask / Deny for each tool individually), rate limiting (max 10 shell execs/hour), per-agent security profiles, and a secret scanner that auto-redacts API keys and PII from logs. You can even approve tools via Discord buttons when you're away from your desk.

Settings > Security Security settings - autonomy levels

1

Autonomy Levels

Choose how much freedom agents have: Supervised (approve everything), Balanced (approve risky only), Autonomous (approve destructive only), or Full / YOLO (no approvals).

2

Directory Access

Restrict which directories the agent can read from and write to. Protect sensitive folders.

Settings > Security (continued) Security settings - MCP and per-agent

3

MCP Server Access

Enable or disable specific MCP servers. Control which tools are available to the agent.

4

Per-Agent Security

Set different security profiles for each sub-agent. A researcher might have web access but no shell access.

5

Blocked Commands

Define specific commands or patterns that should never be executed, regardless of autonomy level.

⚠️

Recommendation: Start with Balanced mode. It lets the agent work efficiently while still asking for approval on potentially risky operations like file deletions or shell commands.

Interface

Adjust font size and chat behavior preferences.

Settings > Interface Interface settings

1

Typography

Adjust the font size: Small, Medium (default), or Large.

2

Send on Enter

Toggle whether Enter sends messages or creates a new line. Use Shift+Enter for the alternative.

3

Show Thinking & Tool Calls

Toggle visibility of the agent's reasoning process and tool execution details in the chat.

Skills

Extend your agent with specialized skills. Skills are instruction sets that teach the agent new capabilities.

Extensible Skill System with Slash Commands

Skills are declarative capabilities defined in simple SKILL.md files with YAML frontmatter. Type /charts to generate visualizations, /code-review for automated PR reviews, /deploy for one-command deployments, or /elevenlabs for AI voice generation. Skills define triggers (when to activate), required tools, dependency checks (env vars, binaries, OS), and can even bundle their own MCP server. Load skills from 5 sources: workspace, project, user, community hub, or bundled. The agent uses metadata-only prompt injection — skills are indexed compactly and full instructions load on-demand, saving thousands of tokens per API call.

Settings > Skills Skills settings

1

Installed Skills

View and manage all loaded skills. Enable or disable each skill individually.

2

Create Custom Skills

Create a SKILL.md file with YAML frontmatter. Define triggers, instructions, required tools, and environment dependencies.

3

Slash Commands

Skills can be invoked as slash commands: type /skill-name in chat to trigger them directly.

4

Automatic Triggers

Skills can trigger automatically when the agent detects a matching request. No manual invocation needed.

Plugins

Extend Sci-pilot with plugins. Plugins can add new tools, modify behavior, and integrate with external services.

Settings > Plugins Plugins settings

1

Plugin System Status

Shows whether the plugin runtime is initialized and ready.

2

Installed Plugins

Add plugins to config/plugins/ or install via npm. Each plugin runs in a sandboxed environment.

3

Diagnostics

Run diagnostics to check plugin health and identify issues. Shows "All systems nominal" when everything is working.

Memory

Persistent memory system that grows over time. Your agent remembers past conversations, learns from experience, and builds a knowledge base.

Persistent Memory with Vector Search & Soul Evolution

Most AI chatbots forget everything between conversations. Sci-pilot has a 3-layer memory system: MEMORY.md for long-term facts, daily diary (auto-indexed by date), and a Memory Bank with typed entries — world facts, experiences, opinions (with confidence scores 0.0–1.0), and per-entity pages (Person.md, Project.md). Search uses hybrid vector + keyword with query expansion, MMR diversity scoring, and temporal decay (older memories rank lower). The Soul Evolution system analyzes your conversations every 3 sessions and automatically updates your agent's personality, learning your name, interests, tech level, communication style, and domain preferences. Your agent literally grows smarter over time.

Settings > Memory Memory management

1

Memory Overview

See total memories, entries, words, and distinct topics stored. Monitor how your agent's knowledge grows.

2

Core Memories

Long-term memories stored in MEMORY.md. The agent automatically saves important context from conversations.

3

Vector Search

Semantic search across all memories using embeddings. The agent retrieves relevant memories when answering questions.

4

Daily Diary

Automatic daily diary entries in diary/YYYY-MM-DD.md. Review what your agent worked on each day.

Communications

Connect your agent to external messaging platforms. Control it from Discord, Telegram, or receive notifications anywhere.

Multi-Channel Notifications — Discord, Slack, Telegram & More

Sci-pilot's Notification Dispatcher routes alerts to 6 channels: WebSocket (UI — always on), Discord (full bridge with !yolo/!safe/!status commands + button-based tool approval), Webhook (HTTP POST with custom headers), Telegram (Bot API), Slack (incoming webhooks), and Email. Notifications have priority levels (low, normal, high, urgent) with emoji mapping and source tracking (heartbeat, task, agent, cron, alert). History is persisted (200 entries) so nothing gets lost. Your agent works 24/7 — and you stay informed from anywhere.

Discord Bridge

Settings > Communications > Discord Discord bridge settings

1

Discord Bot Integration

Connect a Discord bot to control Sci-pilot from any Discord channel. Send messages, approve tools, and monitor agents.

2

Group Context

Enable group mode so the agent can participate in multi-user Discord conversations with context awareness.

Telegram Bot

Settings > Communications > Telegram Telegram bot settings

1

Telegram Bot

Connect via BotFather token. Send and receive messages, get agent notifications directly in Telegram.

2

Agent Notifications

Receive push notifications when tasks complete, errors occur, or the agent needs your attention.

Usage

Track your token consumption and estimated costs across all sessions and providers.

Settings > Usage Usage tracking

1

Daily Metrics

Track today's input tokens, output tokens, total tokens, API calls, and estimated cost at a glance.

2

7-Day History

View usage trends over the past week. Identify usage patterns and optimize your model selection.

Health

Run diagnostics, check system status, and manage backups. Auto-repair fixes common issues automatically.

Settings > Health Health diagnostics

1

Health Check

One-click diagnostic scan. Checks providers, MCP servers, config files, memory, and skills for issues.

2

Auto Repair

Automatically fix common issues like corrupted config, missing directories, or stale sessions.

3

System Overview

Platform info, Node.js version, agent version, active MCP servers, and loaded skills count.

4

Backups

Create and restore backups of settings, personality files, memory, agents, teams, and workflows.

Logs

Real-time log viewer for debugging. Stream the agent engine's console output with level filtering and search.

Settings > Logs Live logs viewer

1

Level Filters

Filter by All, Info, Warn, Error, or Debug. Quickly find issues.

2

Search & Export

Full-text search across logs. Export logs for sharing or debugging. Pause/Follow live stream.

Advanced

Power-user features: autonomous heartbeat, webhooks, cron jobs, background daemon, and engine tuning.

24/7 Autonomous Agent — Heartbeat, Cron & Daemon Mode

This is where Sci-pilot becomes a 24/7 autonomous workforce. The Heartbeat system runs at configurable intervals (default 30min) with quiet hours, deduplication, transcript pruning, and per-agent heartbeat loops (staggered 15s apart). Cron scheduling supports 5-field cron expressions with IANA timezone support, one-shot ISO dates, and interval timers. Webhooks expose an HTTP server (port 18790) for external triggers with per-hook authentication, rate limiting, and IP restriction. The Daemon runs as a background service with auto-restart (max 10 retries), health monitoring, and graceful shutdown. On startup, reconciliation checks for missed jobs during downtime and catches up automatically.

Heartbeat (Autonomous Mode)

Advanced > Heartbeat Heartbeat configuration

1

Enable Heartbeat

When enabled, the agent wakes up on a schedule and performs autonomous tasks — monitoring, reporting, maintenance.

2

Interval & Quiet Hours

Set how often the agent checks in (in minutes) and define quiet hours when it should stay silent.

3

Delivery Channels

Choose where heartbeat notifications go: Discord, Telegram, Webhook, Email, or Slack.

4

HEARTBEAT.md

Write custom instructions for what the agent should do during each heartbeat cycle.

Webhooks & External Triggers

Advanced > Webhooks Webhooks configuration

1

HTTP Webhooks

Create webhook endpoints that trigger agent actions. Integrate with GitHub, CI/CD, monitoring tools, or any HTTP source.

2

Prompt Templates

Define what the agent should do when a webhook fires. Use {{body}} to inject the webhook payload.

3

Background Daemon

Run the agent as a background service with auto-restart and health monitoring. Survives system reboots.

Cron Jobs

Advanced > Cron Jobs Cron jobs configuration

1

Scheduled Tasks

Create jobs that run on a schedule using cron expressions, fixed intervals, or one-shot dates.

2

Task Prompts

Define what the agent should do at each scheduled time. Full natural language instructions.

3

Timezone Support

Cron jobs respect your timezone. Set the timezone per job or use the system default.

Per-Agent Autonomous Mode

Advanced > Per-Agent Autonomy Per-agent autonomous mode

1

Independent Heartbeats

Each sub-agent can have its own heartbeat schedule. A Data Scientist agent can wake up daily to check for new data.

2

Per-Agent Schedule

Set interval and quiet hours independently for each agent. Staggered starts prevent resource contention.

Engine Configuration

Advanced > Engine Engine configuration

1

Agent Engine

Max Iterations (tool-use loops per request) and Tool Timeout (max time for a single tool call).

2

Session Management

Configure daily session reset time and idle timeout. Keep conversations organized and resources clean.

3

Behavior Toggles

Stream Responses for real-time output. Debug Mode for raw API request/response inspection.

4

Data Management

Export all settings, Import from backup, or Reset Everything to factory defaults.