Skip to main content

ionet-ai

Introduction​

ionet-ai is a local knowledge base for ionet. It stores explainable, maintainable, and governable framework knowledge, rules, templates, checklists, and MCP/CLI assembly capabilities.

It is not a general-purpose RAG repository, nor is it an entry point for copying the documentation into another place. Its focus is to provide stable and constrained knowledge assets from ionet to AI coding tools, so tools such as Codex CLI and Claude Code CLI prioritize ionet's real framework boundaries when generating, explaining, reviewing, and modifying ionet code.

Users can gain these benefits:

  • Reduce generic Java drift and framework hallucinations when AI generates ionet code.
  • Use ionet's stable rules, templates, and checklists directly in local projects.
  • Use MCP tools for knowledge retrieval, context assembly, request diagnostics, and project validation.
  • Reuse the same ionet knowledge-base configuration in Codex CLI and Claude Code CLI.
  • Use the complete local repository as the knowledge source, without depending on the maintainer's local training-material directory.

Public entry points:

How to Install in Codex CLI​

Prepare ionet-ai​

First prepare the ionet-ai repository locally and install the MCP runtime dependencies.

git clone https://github.com/iohao/ionet-ai.git
cd ionet-ai
uv sync --extra mcp

You can use the following command to confirm that the CLI is available.

uv run ionet-ai --help

Install to Your Project​

Run the installation script from the ionet-ai repository root to install the knowledge base into the target ionet project.

bash scripts/install-project.sh --project /path/to/your-project

After installation, the following Codex-related entry points will be generated or updated in the target project:

/path/to/your-project/.codex/skills/ionet-ai
/path/to/your-project/AGENTS.md
/path/to/your-project/codex-ionet.sh
/path/to/your-project/.mcp.json

Where:

  • .codex/skills/ionet-ai/ is the readable knowledge asset installed into the project.
  • AGENTS.md is the project-instructions entry point for Codex CLI.
  • codex-ionet.sh is the recommended startup script for Codex CLI.
  • .mcp.json stores the ionet-ai MCP service configuration and can also be used by clients that support project-level MCP.

Start Codex CLI​

After entering the target project root, run:

./codex-ionet.sh

codex-ionet.sh mounts the ionet-ai MCP service in the current Codex process. It does not write to the global ~/.codex/config.toml and does not affect other projects.

If Codex CLI reports unknown MCP server 'ionet-ai', prefer starting the current project with ./codex-ionet.sh instead of writing a global configuration with codex mcp add.

How to Install in Claude Code CLI​

Claude Code CLI uses the same installation script.

Prepare ionet-ai​

git clone https://github.com/iohao/ionet-ai.git
cd ionet-ai
uv sync --extra mcp

Install to Your Project​

Run the following command from the ionet-ai repository root:

bash scripts/install-project.sh --project /path/to/your-project

After installation, the following Claude Code-related entry points will be generated or updated in the target project:

/path/to/your-project/CLAUDE.md
/path/to/your-project/.mcp.json

Where:

  • CLAUDE.md is the project-instructions entry point for Claude Code CLI.
  • .mcp.json is the project-level MCP service configuration used by Claude Code CLI.

The ionet-ai service in .mcp.json is started by a command similar to:

uv run --project /path/to/ionet-ai --extra mcp ionet-ai serve mcp

Start Claude Code CLI​

After entering the target project root, run:

claude

Claude Code CLI reads the CLAUDE.md in the target project and starts the ionet-ai MCP service through .mcp.json. When a project-level MCP service is used for the first time, Claude Code may ask you to confirm whether the service is trusted.

Prompt Tests​

After installation is complete and the CLI has been started, you can enter the following prompts in the target project to test whether ionet-ai can correctly recognize the ionet project structure, generate framework code, and comply with the relevant rules.

  • Write a login example with ionet.
  • I found that the project does not have a startup class yet. Help me add one.
  • Write several broadcast examples. They need to include single-user broadcast, multi-user broadcast, server-wide broadcast, and broadcast to self. Use String as the broadcast data for now.
  • Add an example of metadata and attachment data.
  • In the "broadcast to self" method, add a delayed task of 2 seconds. If my own userId is 10, cancel this delayed task.
  • Help me customize an external server.
  • Add a heartbeat hook.
  • Add a user online/offline hook.
  • Help me add route access permission control.
  • Get the statistical user count in a logic server.
  • Help me extend the JSON data protocol.

Feedback​

If generated results do not conform to ionet conventions, prompts fail to trigger the expected capabilities, or there are questions about project validation results during use, you can provide feedback through GitHub Issues.

When giving feedback, it is recommended to include:

  • The CLI used, such as Codex CLI or Claude Code CLI.
  • The original prompt that was entered.
  • The general structure of the target project, or related class names, package names, and module names.
  • Code snippets or error messages from the generated results that do not meet expectations.
  • If the validation command was run, include the output from validate-project.

Summary​

ionet-ai is better suited as a local AI coding assistance layer for ionet projects: it places stable knowledge, candidate knowledge, rules, templates, checklists, and MCP tools in the same reviewable repository, giving AI tools clear sources, boundaries, and validation methods when they handle ionet projects.

The recommended usage is: install it once in each ionet project through scripts/install-project.sh, then start it with ./codex-ionet.sh in Codex CLI and directly with claude in Claude Code CLI. After code is generated or modified, you can use the following command to check whether the project violates mechanized ionet rules.

uv run --project /path/to/ionet-ai ionet-ai validate-project --project /path/to/your-project