Ionic Essential

The local-first compatibility layer for multi-agent systems.
Register agent contracts, map dependencies, and catch breakages before they ship.

Download the latest release »

Browse Source · Report Bug · Request Feature

Table of Contents

1. About the Project
   • Core Capabilities
   • Built With
2. Getting Started
   • Prerequisites
   • Windows Desktop
   • Install the CLI from PyPI
   • Install From Source
   • Build the Desktop App
3. Usage
4. Privacy and Security
5. Roadmap
6. Contributing
7. License and Trademarks
8. Acknowledgments

About the Project

Agent systems often depend on instruction files whose behavioral contracts are implicit. A small change to one agent's tools, outputs, constraints, or persona can silently break every agent that depends on it.

Ionic Essential turns those instructions into versioned contracts. It keeps a local registry, builds the dependency graph, and checks proposed changes against their consumers before rollout. The same core is available through a desktop app, command-line interface, Python library, and MCP server.

Ionic Essential is open source under the MIT License and has no Ionic account requirement or Ionic telemetry.

(back to top)

Core Capabilities

• Discover agent instruction files such as AGENTS.md and CLAUDE.md.
• Extract contracts for tools, inputs, outputs, capabilities, constraints, persona rules, and dependencies.
• Register and version contracts in a local SQLite registry.
• Visualize direct and transitive dependencies.
• Detect structural compatibility problems locally by default.
• Opt in to semantic review with a configured provider or supported subscription runtime.
• Use Ionic through the desktop app, CLI, Python API, or MCP.
• Work interactively from a bounded terminal cockpit with completion and in-session history.

Built With

• Python 3.11+
• Pydantic
• Typer
• prompt-toolkit
• Electron
• Node.js 22+

(back to top)

Getting Started

Choose the packaged Windows desktop app or install the Python project from source. Neither path requires an Ionic account.

Prerequisites

For the Python CLI, library, or MCP server:

• Python 3.11 or newer
• Git

For desktop development:

• Node.js 22 or newer
• npm
• A compatible Python build environment

Windows Desktop

Download Ionic Essential 0.6.1 from GitHub Releases. The installer is a release asset and is not committed to this source repository.

The current Windows build is not Authenticode-signed. Verify its SHA-256 digest before running it:

7F4104CEAC355594BDA5DB11B60967262765337A34D8AF1F3EC05D5B36837F35

Install the CLI from PyPI

Install the Ionic 0.7.2 CLI from PyPI with:

python -m pip install ionic
ionic

Install the optional MCP integration with:

python -m pip install "ionic[mcp]"
ionic serve

Install From Source

1. Clone the repository.

   git clone https://github.com/tacticocc/Ionic.git
   cd Ionic

2. Install Ionic in editable mode.

   python -m pip install -e .
   ionic version

3. Install the MCP integration when needed.

   python -m pip install -e ".[mcp]"
   ionic serve

Build the Desktop App

cd desktop
npm ci --no-audit --no-fund
npm test
npm run dist:win

Local builds are unsigned unless you supply your own signing identity. Tactico Technologies signing credentials are not stored in this repository.

(back to top)

Usage

Open the interactive terminal

Run Ionic without arguments in a real terminal to open the contract operations cockpit:

ionic

Type / to open the described command palette. Use Up/Down and Tab/Shift-Tab to choose, then Enter to insert a command. /dashboard shows local registry health; /repo add ID PATH selects repositories for the current TUI session, and /workspace scan, check, or sync uses that selection unless you supply an explicit --repo or --manifest. Session repositories are not persisted to Desktop, disk, or the contract registry.

Semantic review remains explicit. /semantic api PROVIDER [MODEL] selects a direct API backend for the current TUI session, /semantic key set PROVIDER opens a masked session-only credential prompt, and /semantic check ... runs the normal Ionic check with --llm. /semantic subscription ... selects a supported official runtime without asking for its token; /semantic consent then shows the runtime-specific disclosure and exact versioned acceptance command. Consent and credentials remain process-local. Configuration alone never starts a model request, and workspace v1 remains structural and offline.

PageUp/PageDown and the mouse wheel scroll output while the command bar remains ready. Tab with an empty command focuses scrollback for Up/Down and g/G, then Tab returns to the command bar. /quit or Ctrl-D exits. The command bar only runs allowlisted Ionic operations; it does not execute shell commands.

All direct commands remain available for scripts and automation. Redirected input/output, CI, IONIC_NO_TUI=1, and Desktop sidecar calls stay non-interactive.

Register agent contracts

Register one instruction file or discover supported files in a directory:

ionic register path/to/AGENTS.md
ionic register path/to/repository

Inspect dependencies

ionic list
ionic graph
ionic status

Check a proposed change

ionic check <contract-id> --against path/to/changed/AGENTS.md

Structural checks are the default. Semantic review requires an explicit --llm opt-in and a configured provider or supported subscription runtime:

ionic check <contract-id> --against path/to/changed/AGENTS.md --llm

Scan a multi-repository workspace

ionic workspace scan --repo app=path/to/app --repo agent=path/to/agent
ionic workspace check --repo app=path/to/app --repo agent=path/to/agent

Workspace v1 checks are structural and local.

Run the MCP server

ionic serve

Use ionic --help or ionic <command> --help for the complete command surface.

(back to top)

Privacy and Security

• Ionic emits no Ionic telemetry.
• Structural analysis and the contract registry remain local.
• Semantic review is always opt-in.
• When semantic review is enabled, selected contract content is handled by the model provider or subscription runtime you configure, under that provider's terms.
• Provider credentials must not be committed, logged, or included in test fixtures.

Do not post customer source code, private contracts, personal data, or credentials in public issues. Report suspected vulnerabilities privately by following SECURITY.md.

(back to top)

Roadmap

Ionic Essential is evolving in public. Proposed work and known problems are tracked through GitHub Issues:

• Open issues
• Feature requests
• Current releases

Roadmap items are proposals, not release commitments. Please open a feature request before starting a substantial behavioral change.

(back to top)

Contributing

Contributions that improve Ionic Essential are welcome.

1. Read CONTRIBUTING.md.
2. Fork the project.
3. Create a focused branch: git checkout -b feature/short-description.
4. Add or update tests for behavioral changes.
5. Run the relevant Python and desktop test suites.
6. Commit your changes and open a pull request using the repository template.

By contributing, you agree that your contribution is provided under this repository's MIT License.

(back to top)

License and Trademarks

The source code is distributed under the MIT License. Applicable third-party terms are listed in THIRD-PARTY-NOTICES.txt.

The MIT License does not grant branding rights to the Ionic or Tactico Technologies names, logos, icons, or trade dress. See TRADEMARKS.md before distributing a modified build.

(back to top)

Acknowledgments

• README structure adapted from Best-README-Template.
• Choose an Open Source License
• Shields.io
• The open-source projects and contributors listed in THIRD-PARTY-NOTICES.txt

Project link: https://github.com/tacticocc/Ionic

(back to top)