Neomage
Multi-provider AI agent engine for Flutter. Robust API clients for Gemini (including Gemini Live bidirectional voice streaming), OpenAI, Anthropic, DeepSeek, Qwen, and Ollama with tool execution, skills, multi-agent swarms, and MCP.
Part of the Open Neom ecosystem.
Features
- Multi-provider — Gemini, OpenAI, Anthropic, DeepSeek, Qwen, Ollama. One interface, any backend.
- Swarm Orchestration (Multi-Agent Swarm) — High-performance concurrent multi-agent scheduler (
SwarmOrchestrator) using a DAG (DependencyGraph) with DFS cycle-detection, topological sorting, work-stealing scheduling, and inter-agent direct/broadcastMessageBus. - Offline Sovereignty & Local AI — Run local GGUF models (e.g. Llama 3.2, Qwen 2.5 Coder) in-process via
LocalLlamaProvider, native offline voice synthesis (Piper/VITS via Sherpa ONNX in isolates), and deterministic JS execution using an isolated QuickJSJsSandboxTool. - IDE Bridge & Editor Integration — WebSocket JSON-RPC edit bridge to VS Code, JetBrains (IntelliJ, PyCharm, etc.), and terminal editors to perform split diffs, diagnostic extraction, atomic edits, and remote file navigation.
- Gemini Live Realtime Voice — Pure-Dart client (
GeminiRealtimeClient) for Gemini's bidirectional voice WebSocket API, streaming audio natively with PCM 16-bit 16 kHz input / 24 kHz output. - Agentic tool system — 31 built-in tools (Bash, FileRead/Write/Edit, Grep, Glob, WebSearch, Agent, etc.) with automatic multi-turn execution loop.
- Streaming — Real-time SSE parsing with typed stream events (
TextDelta,ToolUseStart,ThinkingDelta, etc.). - Skills framework — 283 loadable markdown skills across 40+ categories (architecture, testing, debugging, agents, security, etc.).
- Personality system — 12 modular personality modules (Identity, Cognition, Tools, Agency, Memory, etc.) assembled into a dynamic system prompt with environment context.
- MCP client — Model Context Protocol support for extending capabilities with external tool servers.
- Bash security — Advanced command validation with 23+ security checks (injection detection, IFS validation, quote-obfuscated flags, process substitution blocks, and locale hacks).
- Advanced Context Compaction — Three-phase pipeline including in-memory Microcompaction, reactively-triggered Auto-Compaction, and dual-direction cache-friendly Partial Compaction preserving LLM Prompt Caching.
- Retry with backoff — Configurable exponential backoff with 529/rate-limit awareness.
- Cross-platform — macOS, Linux, Windows, Web, iOS, Android.
Installation
dependencies:
neomage: ^1.0.0
import 'package:neomage/neomage.dart';
Quick Start
1. Configure a provider
import 'package:neomage/neomage.dart';
// Use any OpenAI-compatible provider
final provider = ApiProvider(
apiKey: 'your-api-key',
baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
model: 'gemini-2.5-flash',
);
2. Send messages
final message = Message.user('Explain the builder pattern in Dart');
final response = await provider.complete(messages: [message]);
print(response.textContent);
3. Stream responses
final stream = provider.stream(messages: [message]);
await for (final event in stream) {
if (event is TextDelta) {
stdout.write(event.text);
}
}
4. Use the tool system
// Define tools
final tools = [
ToolDefinition(
name: 'read_file',
description: 'Read contents of a file',
inputSchema: {
'type': 'object',
'properties': {
'path': {'type': 'string', 'description': 'File path to read'},
},
'required': ['path'],
},
),
];
// The query engine handles the agentic loop automatically
final engine = QueryEngine(provider: provider, tools: tools);
final result = await engine.query(
messages: [Message.user('Read the pubspec.yaml file')],
);
5. Validate bash commands
final result = bashCommandIsSafe('ls -la');
// result.isPassthrough → safe
final risky = bashCommandIsSafe('rm -rf / --no-preserve-root');
// risky.isAsk → needs user confirmation
6. Build system prompts with personality
// Load personality modules (call once at startup)
await NeomageSystemPrompt.load();
// Build a context-aware system prompt
final systemPrompt = NeomageSystemPrompt.build(
model: 'gemini-2.5-flash',
workingDirectory: '/home/user/project',
gitBranch: 'feature/auth',
projectLanguage: 'dart',
projectFramework: 'flutter',
loadedSkills: [codingSkill, testingSkill],
);
Supported Providers
| Provider | Default Model | Endpoint |
|---|---|---|
| Gemini | gemini-2.5-flash | generativelanguage.googleapis.com |
| OpenAI | gpt-4o | api.openai.com |
| Anthropic | claude-sonnet-4 | api.anthropic.com |
| DeepSeek | deepseek-chat | api.deepseek.com |
| Qwen | qwen-plus | dashscope.aliyuncs.com |
| Ollama | llama3.1 | localhost:11434 (local) |
Architecture
lib/
├── core/
│ ├── agent/ # System prompt builder, personality loader
│ └── platform/ # Cross-platform abstraction (dart:io stubs for web)
├── data/
│ ├── api/ # ApiProvider, AnthropicClient, OpenAiShim, SSE streaming
│ ├── auth/ # API key + provider config (secure storage)
│ ├── engine/ # QueryEngine — agentic conversation loop
│ ├── tools/ # 31 tools: Bash, FileRead/Write/Edit, Grep, Glob, Agent...
│ ├── compact/ # Context compaction (summarization strategies)
│ ├── services/ # Ollama, MCP, analytics, voice, git, sessions
│ └── commands/ # 24+ slash commands
├── domain/models/ # Message, ContentBlock, ToolDefinition, Permissions, IDs
├── state/ # Sint controllers and reactive state
└── utils/ # 25+ utility modules (config, telemetry, git, etc.)
Example App
The example/ directory contains a full AI coding assistant app built with neomage — demonstrates multi-provider chat, tool execution, skills system, MCP integration, and more.
cd example
flutter pub get
flutter run -d macos # or: -d chrome, -d linux, -d windows
Features: streaming chat, Ollama local models, settings, onboarding, command palette, vim mode, dark/light theme, session browser, MCP panel.
Testing
flutter test
The test suite covers domain models, API error classification, bash security validation, SSE parsing, retry logic, tool definitions, and system prompt assembly.
Acknowledgements
Neomage is built on the shoulders of giants. We gratefully acknowledge the following projects and organizations whose work, APIs, and open-source contributions made this possible:
- Anthropic — For the Claude API and for open-sourcing Claude Code (OpenClaw), whose tool system architecture, system prompt design, agentic loop patterns, and permission model served as the primary reference architecture for Neomage's engine.
- Google — For the Gemini API and the Flutter framework, which powers Neomage's cross-platform capabilities across macOS, Linux, Windows, Web, iOS, and Android.
- OpenAI — For establishing the chat completions API standard that became the lingua franca for AI providers, enabling Neomage's multi-provider compatibility via the OpenAI-compatible shim.
- Qwen (Alibaba Cloud) — For the Qwen model family and DashScope API, expanding Neomage's reach to additional high-quality models.
- Ollama — For making local model inference accessible and enabling Neomage's offline-first capabilities.
License
Apache License — see LICENSE.
Built by the Open Neom community.
Libraries
- core/agent/neomage_system_prompt
- core/platform/native_platform
- core/platform/neomage_io
- core/platform/neomage_io_io
- core/platform/neomage_io_stub
- core/platform/platform_init
- core/platform/platform_init_native
- core/platform/platform_init_web
- core/platform/platform_interface
- core/platform/shell_executor
- core/platform/shell_executor_io
- core/platform/shell_executor_stub
- core/platform/web_platform
- data/analytics/analytics_service
- data/analytics/feature_flags
- data/api/anthropic_client
- data/api/api_provider
- data/api/errors
- data/api/gemini_client
- data/api/local_llama_provider
- data/api/openai_shim
- data/api/retry
- data/api/streaming
- data/auth/auth_service
- data/auth/oauth_service
- data/bootstrap/app_state
- data/bootstrap/bootstrap_service
- data/bridge/bridge_protocol
- data/bridge/ide_bridge
- data/bridge/jetbrains_bridge
- data/bridge/vscode_bridge
- data/commands/builtin/branch_command
- data/commands/builtin/bridge_command
- data/commands/builtin/clear_command
- data/commands/builtin/commit_command
- data/commands/builtin/compact_command
- data/commands/builtin/context_command
- data/commands/builtin/cost_command
- data/commands/builtin/diff_command
- data/commands/builtin/extended_commands
- data/commands/builtin/help_command
- data/commands/builtin/init_verifiers_command
- data/commands/builtin/insights_command
- data/commands/builtin/mcp_add_command
- data/commands/builtin/memory_command
- data/commands/builtin/model_command
- data/commands/builtin/plan_command
- data/commands/builtin/review_command
- data/commands/builtin/security_review_command
- data/commands/builtin/session_command
- data/commands/builtin/terminal_setup_command
- data/commands/builtin/thinkback_command
- data/commands/builtin/ultraplan_command
- data/commands/builtin/xaa_idp_command
- data/commands/command
- data/commands/command_registry
- data/compact/compaction_service
- data/compact/identifier_preserver
- data/compact/queued_compaction_engine
- data/engine/conversation_engine
- data/engine/query_engine
- data/engine/system_prompt
- data/hooks/hook_executor
- data/hooks/hook_manager
- data/hooks/hook_types
- data/hooks/lifecycle_hooks
- data/hooks/permission_hooks
- data/mcp/mcp_client
- data/mcp/mcp_config
- data/mcp/mcp_transport
- data/mcp/mcp_types
- data/memdir/memdir_paths
- data/memdir/memdir_service
- data/memdir/memory_scan
- data/memdir/memory_types
- data/platform/cli_adapter
- data/platform/file_watcher
- data/platform/native_bridge
- data/platform/notification_service
- data/platform/platform_bridge
- data/platform/remote_bridge
- data/platform/remote_session
- data/plugins/plugin_loader
- data/plugins/plugin_service
- data/proxy/upstream_proxy
- Upstream proxy for routing API calls through an intermediary.
- data/remote/remote_permission_bridge
- data/remote/remote_session_manager
- data/remote/sdk_message_adapter
- data/remote/sessions_websocket
- data/server/direct_server
- Direct connect HTTP/WebSocket server for headless and API mode.
- data/services/analytics_service
- data/services/auto_dream_service
- data/services/autocomplete_service
- data/services/clipboard_service
- data/services/compact_service
- data/services/config_service
- Configuration management service for Neomage, ported from Neomage.
- data/services/conversation_service
- data/services/coordinator_service
- data/services/coordinator_service_full
- data/services/diagnostic_runtime_service_impl
- data/services/diff_service
- data/services/git_service
- data/services/history_service
- data/services/lsp_service
- data/services/memory_extraction_service
- data/services/message_normalizer
- data/services/notification_service_full
- data/services/oauth_service
- data/services/ollama_service
- data/services/plugin_activation_service_impl
- data/services/plugin_service
- data/services/project_service
- data/services/prompt_suggestion_service
- data/services/rate_limit_service
- data/services/remote_settings_service
- data/services/search_service
- data/services/session_memory_service
- data/services/settings_sync_service
- data/services/startup_context_service_impl
- data/services/task_service
- data/services/team_memory_service
- data/services/tips_service
- data/services/tool_execution_service
- data/services/voice_service
- data/session/session_history
- data/session/session_memory
- data/session/session_restore
- data/skills/skill
- data/skills/skill_registry
- data/tools/agent_tool
- data/tools/bash_security
- data/tools/bash_tool
- data/tools/bash_tool_full
- data/tools/config_tool
- data/tools/extended_tools
- data/tools/file_edit_tool
- data/tools/file_read_tool
- data/tools/file_write_tool
- data/tools/glob_tool
- data/tools/grep_tool
- data/tools/js_sandbox_tool
- data/tools/lsp_tool
- data/tools/mcp_tool
- data/tools/notebook_edit_tool
- data/tools/plan_mode_tool
- data/tools/powershell_tool
- data/tools/send_message_tool
- data/tools/skill_tool
- data/tools/task_output_tool
- data/tools/task_update_tool
- data/tools/todo_write_tool
- data/tools/tool
- data/tools/tool_registry
- data/tools/tool_schemas
- data/tools/tool_search_tool
- data/tools/web_fetch_tool
- data/tools/web_search_tool
- data/voice/voice_service
- Voice mode service for the Flutter client.
- domain/models/audit/saia_audit_category
- domain/models/audit/saia_audit_check
- domain/models/audit/saia_audit_report
- domain/models/audit/saia_brand_profile
- domain/models/audit/saia_campaign_concept
- domain/models/audit/saia_check_result
- domain/models/audit/saia_copy_framework
- domain/models/audit/saia_creative_brief
- domain/models/audit/saia_grade
- domain/models/audit/saia_health_score
- domain/models/audit/saia_platform_spec
- domain/models/audit/saia_severity
- domain/models/audit/saia_voice_axes
- domain/models/command
- domain/models/compaction_policy
- domain/models/diagnostic_activity
- domain/models/diagnostic_event
- domain/models/entrypoints
- domain/models/entrypoints_full
- domain/models/hook_schemas
- domain/models/hooks
- domain/models/ids
- domain/models/logs
- domain/models/message
- domain/models/normalized_message
- domain/models/permissions
- domain/models/plugin
- domain/models/plugin_activation_plan
- domain/models/plugin_setup_descriptor
- domain/models/startup_context_config
- domain/models/startup_context_entry
- domain/models/startup_context_result
- domain/models/text_input_types
- Types for text input handling, vim mode, and command queuing.
- domain/models/tool_definition
- domain/services/audit/saia_audit_service
- domain/services/audit/saia_creative_pipeline_service
- domain/services/audit/saia_parallel_audit_service
- domain/services/diagnostic_runtime_service
- domain/services/message_normalizer_service
- domain/services/plugin_activation_service
- domain/services/queued_compaction_service
- domain/services/startup_context_service
- localization/app_en_translations
- localization/app_es_translations
- localization/app_translations
- neomage
- Neomage — Multi-provider AI agent engine for Flutter. API clients, tool system, skills, commands, and MCP support. Part of the Open Neom ecosystem.
- neomage_routes
- realtime/gemini_realtime_client
- realtime/gemini_realtime_event
- root_binding
- state/app_state
- ui/buddy/buddy_widget
- ui/controllers/chat_controller
- ui/keybindings/default_bindings
- ui/keybindings/keybinding_resolver
- ui/keybindings/keybinding_types
- ui/screens/chat_screen
- ui/screens/choose_agent_page
- ui/screens/doctor_screen
- ui/screens/mcp_panel_screen
- ui/screens/ollama_setup_screen
- ui/screens/onboarding_screen
- ui/screens/session_browser_screen
- ui/screens/settings_screen
- ui/screens/splash_screen
- ui/styles/output_styles
- Output formatting and styling utilities.
- ui/theme/app_theme
- ui/theme/neomage_theme_full
- Complete theming system for Neomage, ported from Neomage (Neomage).
- ui/vim/vim_mode
- ui/widgets/agent_panel
- ui/widgets/background_tasks_panel
- ui/widgets/command_palette
- ui/widgets/custom_select
- ui/widgets/design_system
- ui/widgets/diff_view
- ui/widgets/feedback_survey
- ui/widgets/input_bar
- ui/widgets/log_panel
- ui/widgets/markdown_preview
- ui/widgets/mcp_tool_views
- ui/widgets/memory_panel
- ui/widgets/message_bubble
- ui/widgets/message_renderer
- ui/widgets/permission_dialog
- ui/widgets/permission_manager
- ui/widgets/plan_mode_view
- ui/widgets/prompt_input
- ui/widgets/sandbox_settings
- ui/widgets/skills_panel
- ui/widgets/status_bar
- ui/widgets/status_notice
- ui/widgets/streaming_text
- ui/widgets/syntax_highlight
- ui/widgets/task_detail_views
- ui/widgets/teams_dialog
- ui/widgets/teleport_view
- ui/widgets/terminal_view
- ui/widgets/tool_output_widget
- ui/widgets/trust_dialog
- utils/analyze/analyze_context
- Context analysis for conversations.
- utils/attachments/attachment_manager
- utils/auth/auth_utils
- Authentication utilities ported from neomage/src/utils/auth.ts.
- utils/auth/feature_gates
- Feature gating and authorization utilities.
- utils/bash/bash_parser
- utils/billing/billing_utils
- utils/cleanup/cleanup_manager
- utils/collapse/collapse_utils
- Message collapsing/grouping utilities for read, search, bash, hook, background bash, and teammate shutdown operations.
- utils/commit/commit_attribution
- Git commit attribution and message formatting.
- utils/computer_use/computer_use_manager
- Computer Use Manager
- utils/config/config_full
- Full configuration management: reading, writing, merging from multiple sources (project, user/global, system).
- utils/config/config_manager
- utils/config/settings
- utils/constants/api_limits
- utils/constants/betas
- utils/constants/error_ids
- utils/constants/figures
- utils/constants/files
- utils/constants/full_constants
- utils/constants/messages
- utils/constants/neomage_assets
- utils/constants/neomage_translation_constants
- utils/constants/oauth
- utils/constants/spinner_verbs
- utils/constants/system
- utils/constants/tool_limits
- utils/constants/tool_names
- utils/context/context_builder
- utils/conversation/conversation_recovery
- utils/cron/cron_manager
- utils/crypto/crypto_utils
- Cryptographic and encoding utilities.
- utils/deep_link/deep_link_handler
- Deep Link Handler
- utils/diff/diff_utils
- Diff utilities for computing, formatting, and applying text diffs.
- utils/doctor/doctor_diagnostic
- utils/effort/effort_manager
- utils/encoding_utils
- utils/env/env_manager
- utils/error/error_handler
- utils/fast_mode/fast_mode
- utils/file/file_operations
- utils/file_history/file_history
- File access history tracking with backup/restore support.
- utils/format/format_utils
- utils/fs/fs_operations
- utils/git/git_diff_utils
- utils/git_utils
- utils/handle_prompt/handle_prompt_submit
- Prompt submission pipeline: validation, exit commands, slash-command dispatch, queuing under concurrency guard, reference expansion, external editor integration, embedded shell command execution, and prompt category classification for analytics.
- utils/heatmap/heatmap_utils
- Heatmap generation, plan management, code indexing detection, and transcript search utilities.
- utils/hooks/hook_manager
- Hook Manager
- utils/ide/ide_utils
- IDE detection, integration helpers, path conversion.
- utils/image/image_utils
- Image handling utilities: resizing, clipboard, storage, validation.
- utils/input/process_user_input
- utils/markdown/markdown_utils
- utils/message_queue/message_queue_manager
- Message queue management, command grouping, memoization, and sequential execution utilities.
- utils/messages/message_utils
- utils/migration/migration_service
- utils/model/model_catalog
- utils/native_installer/native_installer
- Native Installer Implementation
- utils/neomagemd/neomagemd_parser
- NEOMAGE.md file parsing, loading, merging.
- utils/path/path_utils
- Path manipulation utilities ported from Neomage TypeScript.
- utils/permissions/permission_rule
- utils/plugins/plugin_schemas
- Plugin Schemas and Validation
- utils/process/process_manager
- Process management utilities.
- utils/process_utils
- utils/provider/provider_profile
- utils/proxy/proxy_utils
- utils/query/query_helpers
- utils/release/release_utils
- Release notes, auto-updater, semantic versioning, and user management utilities.
- utils/ripgrep/ripgrep_utils
- utils/session/session_storage
- utils/session/session_utils_full
- utils/settings/settings_schema
- utils/shell/shell_provider
- utils/stats/stats_manager
- Statistics tracking and caching for Neomage sessions.
- utils/swarm/swarm_orchestrator
- utils/teammate/teammate_utils
- utils/telemetry/telemetry_service
- utils/text/text_utils
- Text manipulation utilities.
- utils/theme/theme_utils
- utils/tokens/token_counter
- Token counting and estimation utilities ported from Neomage TypeScript.
- utils/tool_result/tool_result_storage
- Utility for persisting large tool results to disk instead of truncating them.
- utils/tool_search/tool_search_utils
- Tool Search utilities for dynamically discovering deferred tools.
- utils/worktree/worktree_manager
- Git worktree management: creating, listing, cleaning up worktrees.