aic One unified TUI

Quick start

The TUI is aic’s primary entry point. Once installed, run aic in your terminal to enter the unified interface (Skills / Contexts / MCP / Ops / Env / Permission / Provider — seven panels in total). CLI commands are mainly for scripting, remote environments, and CI integration.

Prerequisites

RequirementNotes
gitRequired. aic clones the Registry cache via git
TTY terminalRequired for TUI mode; non-TTY (e.g. CI) falls back to text
At least one AI toolClaude Code / Codex CLI / Gemini CLI / OpenCode — install one

1. Install

Download the archive for your platform from the Release page, then unpack it onto your PATH:

# Example: macOS arm64
tar -xzf aic_<version>_darwin_arm64.tar.gz
sudo mv aic /usr/local/bin/
aic --version

A one-line installer (with Gitee / GitHub mirror switching and version pinning) is in preparation.

Windows (Beta)

Windows is currently in Beta: one-line install and tar.gz release archives are not yet available. Watch the Releases pages above for Windows artifacts. Without admin privileges or Developer Mode, Skill distribution falls back to managed copy sync and creates no symlinks.

2. Launch the TUI

Always run aic from your project root. aic resolves project config (.aic/) and managed files (CLAUDE.md / AGENTS.md / GEMINI.md) relative to the current working directory. Running from the wrong directory causes init / sync / context operations to write to the wrong location — config may land in unrelated directories or fail to take effect. cd into your project root before running aic.

aic

After TTY detection the TUI starts automatically; non-TTY environments (such as CI) fall back to plain text output. Cycle through seven panels with tab / shift+tab, jump quickly with h / l.

3. Switch Registry mirror (optional)

By default aic pulls from Gitee (CN-friendly). To switch to GitHub or a private registry:

  1. In the TUI, press , or click the ⚙ icon in the top-right corner
  2. In the Registry settings, switch mirror or enter your private registry address
  3. Save — the next sync will pull from the new address

You can also edit ~/.aic/config.toml directly (see Configuration and paths).

4. Initialize the project

The first time you enter the TUI, trigger init from the Ops panel (or run aic init via CLI).

aic init will:

  1. Detect installed Claude / Codex / Gemini / OpenCode clients
  2. Create .aic/ and .aic/.aicrc in the project root
  3. Update .gitignore to exclude .aic/.aic-env

5. Install your first Skill

From the TUI’s Skills panel: select git-commit, press i to install, then s to sync.

Or via CLI:

aic install git-commit && aic sync

6. Check environment variables

From the TUI’s Env panel, press c to validate. Or via CLI:

aic env check

Lists the variables required by the active Context and any env-required Skills.

7. Activate a project Context

From the TUI’s Contexts panel: use a / s to browse and activate a Context.

Or via CLI:

aic context list
aic context use 02-iteration-evolution

A project can have at most one active Context. Switching Context updates the AIC managed block in declared target files (CLAUDE.md / AGENTS.md / GEMINI.md).

8. Restart AI tool clients after changes

After installing or updating a Skill / MCP / Context, or switching Provider / Permission, you must restart Claude Code / Codex CLI / Gemini CLI / OpenCode for the new configuration to take effect — these tools read their config files only once at startup; a running session does not pick up changes automatically.

Want to keep your current conversation context? Restart by resuming the conversation: exit the client, then use the tool’s resume / continue feature to restore the previous session. The new config takes effect in the fresh session while your conversation history is preserved.

Without a restart, newly installed Skills / MCP / Context or switched Provider / Permission settings will not be picked up by the current session — the tool keeps using the old configuration.

Next steps