A local-first communication and orchestration bridge for connecting multiple AI agents through a shared coordination layer.
Ths README gonna be huge sorry for that..
NavOS - Universal AI Bridge is an experimental multi-agent orchestration system designed to allow different AI agents, models, IDE assistants, and AI clients to communicate through a centralized local bridge.
The project was created around a simple idea:
Let different AI agents work together on the same project without requiring the user to manually copy information between them.
NavOS provides the coordination layer while the connected AI agents remain responsible for their own reasoning, tools, files, terminals, IDEs, and development environments.
Youtube Video Link:
Full one -
Partial one -
Experimental / Research Project
NavOS is currently a research and experimentation project.
The current implementation demonstrates:
AI agent registration
Persistent logical agent identities
Native and web agent classification
Project registration
Commander / Worker roles
Multi-phase project workflows
Agent-to-agent message routing
Phase reports
Project state tracking
Persistent SQLite state
MCP-based communication
Autonomous worker wake-up experiments
Stateless and stateful MCP session handling
Agent lifecycle management
Role-based project access
Local-first operation
Secure MCP tunneling for remote AI clients
However, the project is not currently presented as a finished production-ready agent-to-agent protocol.
One of the major findings during development was that MCP itself is primarily designed around AI clients communicating with MCP servers and tools. True general-purpose agent-to-agent interoperability is a broader problem.
Because of that, the future architecture of NavOS may evolve toward an MCP + A2A-style hybrid or another dedicated agent communication mechanism.
Development is currently paused while the correct long-term multi-agent communication architecture is being evaluated.
NavOS is a local-first AI coordination bridge.
It is designed to sit between multiple AI agents and provide a shared place where they can:
identify themselves
discover other connected agents
register projects
determine their assigned role
create project phases
execute phases
report results
communicate with other agents
track project progress
coordinate work without constantly requiring the human to copy/paste information
The important design principle is:
NavOS coordinates the agents. It does not replace their native working environments.
For example:
Gemini can continue working inside Antigravity IDE.
Codex can continue working inside its own environment.
ChatGPT can act as a web-based Commander.
Each native agent can continue using its own filesystem, terminal, editor, compiler, Git tools, and other capabilities.
NavOS provides the shared coordination layer between them.
Modern AI development tools are becoming increasingly capable, but different AI systems often operate independently.
A typical workflow might look like this:
Human
│
├── Ask ChatGPT for a plan
│
├── Copy plan
│
├── Paste into Gemini
│
├── Gemini modifies files
│
├── Copy Gemini's result
│
├── Paste into ChatGPT
│
├── ChatGPT reviews
│
└── RepeatThe human becomes the communication bus.
This creates several problems:
repetitive copy/paste
loss of context
duplicated explanations
difficulty coordinating multiple agents
no shared project state
no persistent agent identity
no structured task progression
difficult autonomous workflows
NavOS experiments with another model:
┌─────────────────┐
│ Human │
└────────┬────────┘
│
▼
┌─────────────────┐
│ NavOS │
│ AI Bridge │
└───────┬─────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌─────────┐
│ ChatGPT │ │ Gemini │ │ Codex │
│ Web │ │Antigravity│ │ Desktop │
└─────────┘ └──────────┘ └─────────┘The goal is to allow the agents to coordinate through NavOS rather than forcing the human to manually relay every message.
NavOS separates the system into three major layers.
Related MCP server: aichat-mcp
The actual AI systems perform reasoning and work.
Examples:
ChatGPT
Gemini
Codex
IDE-integrated AI agents
Other MCP-compatible AI clients
NavOS provides:
agent identity
agent registration
project membership
role assignment
phase management
communication
state tracking
coordination
Native agents retain control over their own environment.
For example:
Antigravity / Gemini
│
├── Files
├── Terminal
├── Git
├── IDE
├── Compiler
└── TestsNavOS does not need to directly edit those files.
This separation is intentional.
The experimental architecture looks roughly like this:
┌──────────────────────┐
│ Human │
│ │
│ Assigns Commander │
│ Assigns Worker │
└──────────┬───────────┘
│
▼
┌────────────────────────┐
│ NavOS │
│ │
│ Universal AI Bridge │
│ │
│ Agent Identity │
│ Project State │
│ Phase State │
│ Messages │
│ Reports │
│ Role Enforcement │
└───────────┬────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ChatGPT │ │ Gemini │ │ Codex │
│ Web │ │ Antigravity │ │ Desktop │
│ │ │ IDE │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ │ │
▼ ▼ ▼
Commander Worker Agent
│
▼
Native Project FilesThe exact communication architecture is still under evaluation.
NavOS is built around several concepts.
An AI client connected to NavOS.
Each logical agent has a persistent identity.
A project registered inside NavOS.
A project represents a workspace that agents can coordinate on.
A project is divided into phases.
For example:
Phase 1
Inventory the project
↓
Phase 2
Create README contract
↓
Phase 3
Implement validation
↓
Phase 4
Create tests
↓
Phase 5
Final verificationThe AI responsible for coordinating the project.
The Commander decides:
what should happen
how the project should be divided
what phase should run next
what information the Worker needs
when a phase is complete
The AI responsible for performing an assigned phase.
The Worker:
receives the current phase
works inside its native environment
modifies files when required
runs tests
reports results
waits for the next phase
NavOS distinguishes between two major types of agents.
A native agent has access to an actual local project directory.
Example:
Gemini
Antigravity IDE
C:\Projects\MyProjectThe directory identifies the environment in which the agent is operating.
Native agents can participate as Workers.
A web agent does not have direct filesystem access to the local project.
Example:
ChatGPT Web
directory = nilA web agent can act as a Commander or coordinator, but cannot directly become a Worker in the local native-workspace model.
One of the most important parts of NavOS is persistent agent identity.
A temporary MCP transport connection is not treated as the permanent identity of an agent.
Instead, NavOS separates:
Transport Session
≠
Logical Agent IdentityThis distinction became necessary because some AI clients maintain persistent MCP connections while others may create new HTTP requests or sessions.
Without persistent identity, one logical AI could appear as:
agent-1
agent-2
agent-3
agent-4
agent-5
...even though it is actually the same AI client.
NavOS therefore treats the logical agent identity as persistent state.
An agent explicitly connects to NavOS through the connection mechanism.
The agent provides three important pieces of identity information:
Example:
GPT-5.6 Lunaor:
GeminiExample:
ChatGPT Web PCAntigravity IDECodex DesktopNative agents provide their actual working directory.
Example:
C:\Projects\MyProjectWeb agents use:
nilThis distinction allows NavOS to understand the difference between a native workspace agent and a web-based agent.
Role assignment is intentionally controlled by the human.
Agents do not automatically assign themselves as Commander or Worker.
The intended workflow is:
Human
│
├── Connect Agent A
├── Connect Agent B
│
▼
NavOS Dashboard
│
├── Select Commander
└── Select WorkerThis prevents an agent from deciding its own authority within a project.
Projects are registered with NavOS.
A project can contain:
project metadata
registered agents
Commander
Worker
phases
reports
communication
current state
The actual project files remain in the native agent's workspace.
NavOS stores coordination information rather than becoming the project's filesystem.
The project workflow is based on phases.
A Commander can create phases such as:
Phase 1
Project inventory
Phase 2
Documentation
Phase 3
Implementation
Phase 4
Testing
Phase 5
Final verificationEach phase has a lifecycle.
Conceptually:
Pending
│
▼
Active
│
▼
CompletedThe Worker works on the active phase and submits a report when finished.
One of the most important experiments performed with NavOS was an autonomous Commander → Worker workflow.
The intended workflow is:
Human
│
│ Initial instruction
▼
Commander
│
│ Creates phases
▼
NavOS
│
│ Phase 1
▼
Worker
│
│ Performs work
│
│ Submits report
▼
NavOS
│
│ Advances phase
▼
Worker
│
│ Receives next phase
│
│ Performs work
▼
...The human does not need to manually relay each phase.
A simplified project might look like this:
Complete this project with the Worker.The Commander examines the project and creates:
Phase 1:
Inventory existing files
Phase 2:
Document configuration requirements
Phase 3:
Implement configuration validation
Phase 4:
Create automated tests
Phase 5:
Perform final verificationThe Worker then executes the phases.
Example:
Commander
│
│ Phase 1
▼
Worker
│
│ Inventory complete
▼
Report
│
▼
NavOS
│
│ Phase 2
▼
Worker
│
│ Documentation complete
▼
Report
│
▼
NavOS
│
│ Phase 3
▼
...Different AI clients behave differently when they are waiting.
During development, NavOS experiments investigated how native AI environments react to background tasks, scheduled execution, MCP notifications, and heartbeat-style execution.
A key discovery was:
An MCP notification alone does not necessarily cause an idle AI model to start a new reasoning turn.
However, some environments can react to completion of a background task.
For example, Antigravity was tested with a background process that waited and then completed.
The completion caused the AI environment to resume.
Codex was found to behave differently, with heartbeat/scheduled execution providing a mechanism for starting a new reasoning turn.
ChatGPT Web was also tested with scheduled execution.
These experiments demonstrated that autonomous multi-agent workflows depend not only on the server protocol but also on the behavior of each AI client.
NavOS currently exposes its coordination functionality through the Model Context Protocol (MCP).
MCP allows compatible AI clients to discover and call tools exposed by NavOS.
Conceptually:
AI Client
│
│ MCP
▼
NavOS MCP Server
│
├── Agent management
├── Project management
├── Phase management
├── Messaging
└── CoordinationMCP was useful because modern AI clients increasingly support MCP servers.
This makes it possible to expose NavOS functionality without building a completely custom integration for every AI client.
Instead of:
ChatGPT integration
Gemini integration
Codex integration
IDE integration
...the experiment can expose a common MCP interface.
One of the most important findings from the project is that:
MCP is not inherently a complete agent-to-agent communication protocol.
MCP primarily provides a mechanism for an AI client to communicate with a server and use tools/resources exposed by that server.
The desired NavOS architecture is more ambitious:
Agent A
│
│
▼
Agent Bwith autonomous agent interoperability.
That raises additional questions around:
agent identity
agent discovery
task delegation
message delivery
agent capabilities
agent lifecycle
asynchronous communication
task state
authentication
authorization
agent-to-agent responses
wake-up behavior
These are broader than simply exposing tools through MCP.
This discovery is one of the reasons the project is currently paused while the long-term architecture is evaluated.
NavOS had to solve a subtle problem:
MCP transport sessionand:
logical AI agentare not necessarily the same thing.
A persistent SSE client may maintain one transport session for a long time.
A stateless HTTP client may create a new transport session for every request.
Therefore:
Transport Sessionmust be treated as temporary.
While:
Logical Agentmust persist.
The database therefore stores logical agent information independently from temporary transport state.
Stateless clients introduced an additional challenge.
A client may successfully connect once and then make a later request using a new HTTP transport.
NavOS therefore needs to re-establish the logical agent context for subsequent requests.
The architecture was designed around persistent agent_id information rather than assuming that a transport session will always survive.
This was extensively tested during development.
Native agents cannot simply be identified by:
model
+
location
+
directoryand automatically merged.
Two independent AI agents may intentionally operate in the same directory.
For example:
Gemini
Antigravity IDE
C:\Projects\Testand:
Another Agent
Another Client
C:\Projects\Testmay both legitimately exist.
Therefore, native agent identities remain separate logical entities.
Web agents have no local project directory.
They therefore use:
directory = nilFor the experimental architecture, web agent identity can use model/client-location information for deterministic recovery.
This is intentionally different from native agents because multiple native agents may share a filesystem directory.
NavOS uses SQLite for persistent coordination state.
The database stores information such as:
agents
projects
project membership
roles
phases
reports
messages
lifecycle information
The database is a backend implementation detail.
It is not intended to become the user's primary interaction interface.
The dashboard communicates with NavOS rather than requiring direct database interaction.
NavOS includes a web dashboard for human oversight and assignment.
The dashboard is intentionally minimal and focused on orchestration.
The design includes:
Displays:
NavOS status
uptime
connected agent count
project count
Shows agents that have explicitly connected.
Example:
Connected Agents
GPT-5.6 Luna
ChatGPT Web PC
WEB
Gemini
Antigravity IDE
NATIVE
Codex
Codex Desktop
NATIVEThe human can assign:
Commander → WorkerThe dashboard provides explicit Commander and Worker selection.
This is intentionally human-controlled.
Projects are displayed with a compact view of current activity.
The dashboard does not attempt to replace the agents' native development environments.
Security was a major part of the public-release audit.
The project was reviewed for:
hardcoded secrets
API keys
tokens
passwords
private keys
filesystem path leaks
SQL injection
command injection
role bypasses
unsafe network binding
sensitive local data
accidental database commits
The audit found no embedded secrets.
The server defaults to:
127.0.0.1rather than binding to all network interfaces.
This is important because NavOS is designed as a local-first system.
The server can therefore remain local unless the user intentionally exposes it through another mechanism.
Database operations use parameterized SQL queries rather than constructing SQL statements directly from user-controlled values.
This reduces the risk of SQL injection.
Where external processes are executed, argument arrays are used rather than constructing shell commands from untrusted strings.
The implementation uses process execution with explicit argument separation.
Project roles are enforced server-side.
The client UI is not treated as the security boundary.
For example, simply changing a dashboard selection or sending a crafted request should not grant an agent Commander or Worker permissions.
NavOS checks the authenticated logical agent and its project role.
NavOS is designed to operate locally.
Local runtime information such as:
database contents
local agent state
local project paths
temporary runtime state
should not be committed to the public repository.
The public-release audit specifically checked for personal filesystem paths and local runtime data.
The project was audited before public release.
The audit checked for:
personal filesystem paths
OneDrive paths
usernames
API keys
authentication tokens
passwords
private keys
bearer tokens
JWTs
webhook URLs
local databases
The repository was cleaned so local runtime data and configuration are ignored.
.gitignoreRuntime and local-only data is excluded from the repository.
Examples include:
config/config.json
data/*
scratch/
coverage/
.nyc_output/
.temp/while appropriate example/configuration files remain available for users.
NavOS has been heavily tested during development.
The final public-release verification included:
74 / 74 JavaScript / TypeScript tests passedAdditional Python project tests passed:
9 / 9
11 / 11The test suites covered areas including:
dashboard redesign
identity lifecycle
session lifecycle
reconnect behavior
stateless clients
ChatGPT simulation
Codex simulation
Antigravity behavior
role isolation
native agent separation
stale session handling
project filtering
agent deletion
lifecycle hardening
A major part of the NavOS development process was testing whether different AI clients could remain in an autonomous Commander → Worker workflow without requiring the human to manually press "Continue" or send every next instruction.
The experiments revealed that different AI clients behave very differently when they are idle.
NavOS itself can track that a new phase is ready, but the AI client must have some mechanism that causes it to start or resume a reasoning turn.
The following clients were tested.
Role tested: Worker
Environment: Antigravity IDE
Result: ✅ Successfully tested
Antigravity was the most successful environment for the autonomous Worker loop.
Antigravity supports background tasks.
A background watcher process was used to wait for changes in NavOS project state.
The general workflow was:
Antigravity Worker
│
│ Wait for next phase
▼
Background Watcher
│
│ Poll NavOS
▼
Phase becomes available
│
▼
Watcher exits
│
▼
Background task completes
│
▼
Antigravity wakes/resumes
│
▼
Gemini continues reasoning
│
▼
Worker executes phaseThe important discovery was that completion of a background task can wake/resume Antigravity's AI workflow.
This made it possible to build a practical waiting mechanism around NavOS.
Experiments
A simple delayed background task was tested using a command equivalent to:
Wait 10 seconds → complete task → output wake-up marker
Antigravity resumed automatically when the background task completed.
A longer one-shot delay was also tested.
The same mechanism successfully allowed Antigravity to remain waiting for NavOS and resume when the required condition occurred.
MCP notification behavior
MCP notifications by themselves were also investigated.
Notifications such as:
notifications/message progress resource updates tools/list changes
do not automatically cause an idle Gemini/Antigravity model to begin a new reasoning turn.
Therefore:
MCP notification ≠ AI wake-up
The practical solution was to use a background task whose completion causes the Antigravity environment to resume the model.
Result
Antigravity successfully acted as the NavOS Worker in the full autonomous project test.
Role tested: Commander
Environment: Codex Desktop
Result: ✅ Successfully tested
Codex was successfully used as the Commander in the autonomous multi-phase workflow.
However, Codex behaves differently from Antigravity.
Background process behavior
A detached/local background process can continue running while Codex is idle.
However:
Background process finishes ≠ Codex automatically starts a new reasoning turn
Therefore, simply running a watcher process was not sufficient to wake Codex.
Heartbeat / Scheduled Execution
Codex's heartbeat/scheduled execution mechanism was tested successfully.
The workflow was:
Codex
│
│ Creates/starts workflow
▼
NavOS
│
│ Worker performs phase
▼
NavOS state changes
│
│
▼
Codex heartbeat
│
│ Starts a fresh reasoning turn
▼
Codex checks NavOS
│
▼
Codex continues workflowA one-time heartbeat test successfully caused Codex to wake and execute a new reasoning turn without a manual user message.
The test produced the expected wake-up output:
NAVOS_CODEX_HEARTBEAT_WAKE_TEST Result
Codex successfully operated as the Commander in the full autonomous test.
Role tested: Commander / Coordinator
Environment: ChatGPT Web
Result: ✅ Wake-up mechanism tested
ChatGPT Web was tested using scheduled/heartbeat-style execution.
The important difference is that a scheduled ChatGPT execution does not necessarily continue inside the exact same conversation turn.
Instead, it can start a new ChatGPT turn/context.
The tested workflow was:
ChatGPT
│
│ Initial turn
▼
NavOS
│
│ Wait
▼
Scheduled execution
│
▼
New ChatGPT turn
│
▼
Reconnect to NavOS
│
▼
Check persistent NavOS state
│
▼
Continue coordinationA heartbeat test successfully woke ChatGPT and caused it to reconnect to NavOS.
The resulting test confirmed:
NavOS Universal AI Bridge: ONLINE Active connections: 3 Registered projects: 1 ChatGPT agent: CONNECTED
This demonstrated that ChatGPT can be used with an external persistent coordination layer even though the scheduled execution may occur in a new chat/turn context.
Important limitation
ChatGPT Web does not behave like a persistent native IDE process.
A scheduled wake-up should therefore be treated as:
New reasoning turn + Persistent external NavOS state
rather than:
Same conversation continuously running
This means NavOS must keep enough persistent state for the AI to reconstruct what is happening when it wakes.
Cross-Client Wake-Up Comparison
The experiments showed three different behaviors.
AI Client Tested Role Wake Mechanism Result Antigravity / Gemini Worker Background task completion ✅ Successful Codex Desktop Commander Heartbeat / scheduled execution ✅ Successful ChatGPT Web Commander / Coordinator Scheduled execution / heartbeat-style wake ✅ Successful
The mechanisms can be summarized as:
┌─────────────────────┬──────────────────────────────┐ │ AI Client │ Wake Mechanism │ ├─────────────────────┼──────────────────────────────┤ │ Antigravity/Gemini │ Background task completion │ │ Codex Desktop │ Heartbeat / scheduled turn │ │ ChatGPT Web │ Scheduled new turn │ └─────────────────────┴──────────────────────────────┘ What Did NOT Work
One of the most important findings was that NavOS cannot assume that sending an MCP notification will wake an idle AI model.
The following general assumption was tested and found to be unreliable:
NavOS
│
│ MCP notification
▼
Idle AI
│
└── Automatically starts thinking
Instead, the observed behavior was:
NavOS
│
│ MCP notification
▼
AI client
│
└── Notification may be received,
but idle model does not necessarily wakeTherefore, the autonomous loop depends on both sides:
NavOS must maintain persistent project/phase state. The AI client must provide some mechanism capable of starting/resuming execution. Full Autonomous 5-Phase Test
The most important end-to-end experiment used:
Commander:
Codex Desktop
Worker:
Gemini / Antigravity IDE
The project was divided into five phases.
Phase 1
Baseline project inventory
↓
Phase 2
README contract
↓
Phase 3
Configuration validation
↓
Phase 4
Automated testing
↓
Phase 5
Final verificationThe Worker executed the phases inside its native project environment while the Commander coordinated the workflow.
The test completed all five phases autonomously.
The final test result included:
11 / 11 tests passed
The original project files were preserved during the experiment, including the baseline configuration and test files.
This was the first major proof that the NavOS Commander → Worker concept could operate across two different AI environments without requiring the human to manually relay every phase.
What These Experiments Proved
The experiments demonstrated several important points.
AI agents can participate in an external persistent workflow
An AI does not need to store the entire project workflow inside its own conversation.
NavOS can maintain:
Agent Project Role Phase Report Message State
outside the AI conversation.
Different AI clients require different wake strategies
There is no universal "wake the AI" mechanism.
Instead:
Antigravity → background task completion
Codex → heartbeat / scheduled execution
ChatGPT → scheduled new turn 3. Persistent external state is extremely important
Because some clients may start a completely new reasoning turn, NavOS needs to remain the source of truth for project coordination.
Conceptually:
AI memory + NavOS persistent state = Recoverable workflow 4. MCP alone does not solve autonomous execution
MCP can provide the communication interface, but it does not guarantee that an idle AI client will spontaneously begin another reasoning cycle.
This became one of the major architectural discoveries of the project.
Experimental Conclusion
The experiments demonstrated that autonomous multi-agent workflows are technically possible, but the implementation depends heavily on the execution model of each AI client.
The most successful tested combination was:
Codex Desktop │ │ Commander ▼ NavOS │ │ Phase coordination ▼ Antigravity / Gemini │ │ Worker ▼ Native Project
The experiment successfully completed a five-phase development workflow with no manual phase-by-phase message relay.
However, these experiments also revealed that the communication protocol and AI wake-up mechanism are separate problems.
NavOS can know that work is ready.
The remaining question is how the target AI agent should reliably receive that state change and begin its next reasoning cycle.
This distinction is one of the primary reasons the project's next-generation architecture is being evaluated before further development continues.
I'd definitely keep this section in the public README. It's actually one of the strongest parts of the project story.
The really interesting result isn't just "I connected Gemini, Codex and ChatGPT."
It's this:
NavOS State
│
▼
┌──────────────────┐
│ Phase Available │
└────────┬─────────┘
│
┌────────┼─────────┐
▼ ▼ ▼
Agy Codex ChatGPT
│ │ │
Background Heartbeat Scheduled
completion /schedule new turn
│ │ │
▼ ▼ ▼
Wakes Wakes Wakes
Same NavOS state → completely different wake mechanisms depending on the AI client.
---
# Build Verification
The project also passed the build verification step.
npm run build
completed successfully during the public-release audit.
The project is organized roughly around the following areas:
NavOS - Universal Bridge MPC/
│
├── src/
│ ├── db.ts
│ ├── index.ts
│ ├── mcp.ts
│ ├── sessions.ts
│ │
│ └── tools/
│ ├── identity.ts
│ ├── orchestration.ts
│ └── git.ts
│
├── config/
│ └── config.example.json
│
├── data/
│ └── .gitkeep
│
├── test-project/
│
├── tests/
│
├── package.json
├── tsconfig.json
├── .gitignore
└── README.mdThe exact file structure may evolve as the architecture changes.
Typical requirements include:
Windows / compatible development environment
Node.js
npm
SQLite support
An MCP-compatible AI client
Optional:
Antigravity IDE
Codex
ChatGPT
Gemini
Secure MCP Tunnel
Clone the repository:
git clone <repository-url>
cd "NavOS - Universal Bridge MPC"Install dependencies:
npm installCreate a local configuration based on the example configuration.
config/config.example.jsonCopy it to:
config/config.jsonThe local configuration file is intentionally ignored by Git.
Do not commit personal credentials, tokens, private keys, or local environment-specific secrets.
Start the development server using the project's configured npm scripts.
For example:
npm run devThe local dashboard is served by the NavOS server.
The MCP endpoint is available locally according to the configured server settings.
The default local binding is:
127.0.0.1A compatible AI client connects to NavOS through MCP.
The intended workflow is:
1. Start NavOS
2. Open the AI client
3. Connect the client to NavOS
4. Explicitly call the connection mechanism
5. Provide:
- model
- client location
- directory
6. NavOS establishes the logical agent identityOnly after explicit connection should the agent appear as connected.
A native agent might identify itself as:
Model:
Gemini
Client:
Antigravity IDE
Directory:
C:\Projects\MyProjectNavOS then knows:
Type:
NATIVEand associates the agent with its workspace.
A web agent might identify itself as:
Model:
GPT-5.6 Luna
Client:
ChatGPT Web PC
Directory:
nilNavOS recognizes:
Type:
WEBA native agent can register its project with NavOS.
The project registration associates the logical project with the native workspace.
Conceptually:
Agent
│
│ register_project
▼
NavOS
│
▼
ProjectProject membership is tracked separately from the agent's global identity.
Once agents and a project exist:
Human
│
├── Select Commander
│
└── Select Worker
│
▼
NavOS
│
▼
Commander
│
├── Analyze project
├── Create phases
└── Coordinate Worker
│
▼
Worker
│
├── Execute phase
├── Modify files
├── Run tests
└── Submit report
│
▼
NavOS
│
▼
Next phaseNavOS includes communication primitives intended for coordination between agents.
Examples include:
send_agent_messageand project/phase reporting mechanisms.
The exact tool names and schemas may evolve while the long-term communication architecture is being evaluated.
Workers can submit reports after completing phases.
A report can contain information such as:
work performed
files changed
tests executed
results
problems encountered
remaining work
The Commander can use the report to determine what should happen next.
The goal is not to eliminate the human completely.
The intended model is:
Normal work
↓
Agents coordinate autonomously
↓
Human stays out of the loopBut:
Ambiguity
↓
Agent requests clarification
↓
Human responds
↓
Work continuesThis makes the human a supervisor rather than a message relay.
NavOS is designed to be local-first.
When a remote AI client needs to access a locally running NavOS instance, a secure tunneling mechanism can be used instead of directly exposing the local server to the public Internet.
During development, OpenAI Secure MCP Tunnel was used to connect ChatGPT Web to the local MCP server.
Conceptually:
ChatGPT Web
│
│ Secure MCP Tunnel
▼
Local NavOS
│
▼
127.0.0.1:3020The tunnel is external infrastructure and is not the core NavOS architecture.
Clone the repository and install dependencies:
npm installBuild:
npm run buildRun tests:
npm testDevelopment should preserve the following principles:
Do not move native file operations into NavOS unnecessarily.
Do not treat MCP transport sessions as permanent agent identities.
Do not allow agents to self-assign project roles.
Do not merge independent native agents simply because they share a directory.
Keep authentication and authorization server-side.
Keep local runtime data out of Git.
Avoid unnecessary external dependencies.
The primary JavaScript / TypeScript test suite can be run with:
npm testBuild verification:
npm run buildThe experimental test project also contains Python validation tests.
NavOS was designed around local operation.
The system should not require a cloud backend simply to coordinate agents operating on a local machine.
A temporary network connection is not an agent.
The logical AI identity must survive transport reconnections.
Agents do not decide their own authority.
The human assigns:
Commander
Workerthrough the orchestration layer.
A native agent works in its own environment.
NavOS should not become a remote filesystem editor simply to coordinate the agent.
NavOS coordinates work.
The AI agents execute the actual work.
This keeps the bridge lightweight and avoids turning NavOS into another IDE or remote execution framework.
NavOS is not intended to be:
an AI model
an LLM
an IDE
a replacement for Git
a remote desktop
a filesystem management service
a cloud coding environment
a model hosting platform
a general-purpose operating system
a replacement for MCP
currently a finalized A2A implementation
The name "NavOS" refers to the project's orchestration/coordination concept rather than an operating system kernel.
The biggest architectural limitation discovered during development is that MCP alone does not fully solve autonomous agent-to-agent interoperability.
Further architecture research is required.
Different AI clients handle:
MCP sessions
background tasks
notifications
scheduled execution
heartbeats
reconnects
idle states
differently.
Therefore, an autonomous workflow cannot assume identical behavior across all AI clients.
Web-based AI clients may create new transport sessions between turns.
Persistent logical identity therefore requires external state and explicit identity handling.
A server can know that a phase is ready.
That does not automatically mean an idle AI client will wake up.
The client must provide an appropriate mechanism such as:
background task completion
heartbeat
scheduled execution
persistent active turn
another supported wake mechanism
The project demonstrated that a multi-agent workflow can be built around the current design, but the long-term protocol and communication architecture remain open questions.
The next stage of NavOS depends heavily on solving the agent-to-agent communication problem correctly.
Possible directions include:
MCP
+
A2Aor another dedicated communication layer.
A potential future architecture could look like:
┌──────────────┐
│ Human │
└──────┬───────┘
│
▼
┌─────────────────┐
│ NavOS │
│ Orchestrator │
└────────┬────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Agent A │◄─────────►│ Agent B │
└──────────┘ └──────────┘
│ │
▼ ▼
Tools Tools
Files IDE
Git TerminalThe exact protocol has intentionally not been finalized.
Local NavOS server
SQLite backend
MCP integration
Agent registration
Persistent logical agent identity
Native/Web agent distinction
Project registration
Project membership
Commander / Worker model
Phase-based workflow
Phase reporting
Agent messaging
Role enforcement
Dashboard
Stateless session handling experiments
SSE lifecycle handling
Reconnect handling
Agent deletion handling
Autonomous wake-up experiments
Public-release security audit
Secret scan
Privacy scan
Build verification
Automated regression testing
Final autonomous multi-agent protocol
Long-term agent-to-agent communication architecture
MCP + A2A integration decision
Production architecture
Large-scale multi-agent deployment
Contributions, experiments, architecture discussions, and protocol ideas are welcome.
Because the project is currently in an experimental stage, architectural discussions are especially valuable.
If you want to contribute, consider focusing on:
agent communication protocols
MCP interoperability
A2A interoperability
asynchronous agent communication
persistent agent identity
agent discovery
autonomous workflow design
security
authentication
authorization
lifecycle management
Before making major architectural changes, please open an issue or discussion so the design can be evaluated first.
NavOS was built around a simple question:
What happens when AI agents stop working alone and start working together?
The interesting part isn't simply making another AI tool.
The interesting part is creating the infrastructure that allows different AI systems to cooperate while keeping their own capabilities and environments.
The ideal workflow looks something like:
Human
│
│ "Complete this project."
▼
Commander
│
│ Plans
▼
NavOS
│
│ Delegates
▼
Worker
│
│ Builds
▼
NavOS
│
│ Reports
▼
Commander
│
│ Reviews
▼
Worker
│
│ Continues
▼
Completed ProjectThe human should not have to be the network cable between every AI.
NavOS was developed as an independent experimental project exploring:
Multi-agent AI systems
MCP
AI orchestration
Autonomous workflows
Local-first AI infrastructure
IDE-based AI agents
Persistent agent identity
Human-supervised agent collaboration
NavOS is an experimental research project.
It should not be considered production-ready infrastructure for security-critical, safety-critical, financial, or otherwise high-risk workloads without independent security review and appropriate hardening.
AI client behavior may change independently of NavOS.
Protocol support may also change as MCP, A2A, AI clients, and agent frameworks continue to evolve.
See the repository license file for the terms governing use and distribution.
Universal AI Bridge
Connect.
Coordinate.
Collaborate.This server cannot be deployed
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project management MCP for AI agents with safe task reads and writes.
