ionic 0.6.2

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

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.

Built With

• Python 3.11+
• Pydantic
• Typer
• 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.6.2 CLI from PyPI with:

python -m pip install ionic
ionic version

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

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)