Core concepts

The TUI is aic’s primary way of working. CLI is auxiliary (scripting, remote environments, CI integration). This page is organized “TUI first, CLI second”. Every concept answers: where is it configured, who manages it, and what problem does it solve.

1. TUI (unified terminal interface)

The TUI is aic’s primary entry point. Run aic in your terminal to enter a UI with seven panels:

Panel	Main responsibility
Skills	Install, update, sync Skills; filter by state
Contexts	Activate / deactivate project Context templates
MCP	Manage MCP server installation and distribution
Ops	Day-to-day operations (`init` / `sync` / `update` / bulk update)
Env	List and edit project / global env variables
Permission	Permission presets (Codex today)
Provider	Switch local provider profiles

aic            # Auto-enter TUI after TTY detection
aic tui        # Explicitly enter TUI

tab / shift+tab: cycle panels
h / l: jump left / right
, or the ⚙ icon top-right: open settings (theme switching, Registry mirror configuration)
ctrl+? / ctrl+/ / f1: help
q / ctrl+z: confirm exit

Per-panel key bindings

Panel	Common keys
Skills	`1..6` to filter by state (all / installed / available / outdated / broken / env-missing); `i` install, `u` update, `r` remove, `s` sync, `U` bulk update
Contexts	`a` / `s` activate or switch; `u` update current Context; `r` deactivate current Context; `e` jump to variables
MCP	`i` / `u` / `r` install / update / precise-remove; `s` sync
Env	`enter` / `e` edit a variable; `a` add; `c` check; `r` refresh
Provider	`←` / `→` switch sub-tabs; `↑` / `↓` select; `enter` / `s` switch; `e` edit current profile

enter toggles list / detail focus in every panel; the detail view reuses the same Markdown renderer as Skills.

Settings

Open the settings panel via , or the ⚙ icon:

Theme: dark (default) / light / auto (follow system) — persists to tui_theme in ~/.aic/config.toml
Registry mirror: switch Gitee / GitHub or enter a private registry address — writes to ~/.aic/config.toml

2. Skills

What is it? A Skill is a directory containing SKILL.md with YAML frontmatter (name / version / description / tags) that aic installs and links into target tool directories.

Where is it configured? Installed Skills land in <project>/.aic/.aicrc (declaration) plus per-tool directories (links). See Configuration and paths.

Who manages it? Skills panel (tab to Skills) or CLI (aic install / update / remove / sync).

What problem does it solve? Keep AI tool prompts and behavior definitions in project files that travel with git, so the team shares one source of truth.

3. Context

What is it? A Context is a project-level Markdown template (CONTEXT.md with YAML frontmatter) used to inject team conventions, project background, and coding standards into AI tools at once.

Where is it configured? Declared in .aic/.aicrc under context.use; rendered output is written into target files declared by the Context (CLAUDE.md / AGENTS.md / GEMINI.md), updating only the AIC managed block.

Who manages it? Contexts panel or CLI (aic context use / list / show / preview / update / remove).

What problem does it solve? Project conventions travel with the project, independent of personal global config. New team members see the same Context right after init.

A project can have at most one active Context. Switching is blocked if required variables are missing, and the TUI jumps to the Env panel automatically.

4. MCP servers

What is it? MCP (Model Context Protocol) servers extend AI tools with external capabilities. aic parses a unified MCP manifest and dispatches the configuration into supported tool configs (claude.json / ~/.codex/config.toml / ~/.gemini/settings.json / opencode.json).

Where is it configured? Declared in the mcp section of .aic/.aicrc; written into tool global or project configs.

Who manages it? MCP panel or CLI (aic mcp install / update / remove / sync).

What problem does it solve? Share one MCP server across multiple tools without manually maintaining duplicates.

Note: Codex does not support SSE. OpenCode only maintains the top-level mcp field of opencode.json, and does not manage OpenCode permission rules or OAuth.

5. Environment variables

What is it? Env is a set of key-value pairs that env-required Skills and the active Context need to function.

Where is it configured?

Project variables: <project>/.aic/.aic-env
Global variables: ~/.aic/aic-env

Who manages it? Env panel or CLI (aic env add / edit / promote / check / list).

What problem does it solve? Sensitive values stay out of Git. aic env check surfaces missing variables before you hit runtime errors, and promote upgrades a project-local debug value to global.

6. Permissions

What is it? Permission presets apply uniform permission settings across tools (e.g. Codex’s approval_policy / sandbox_mode).

Where is it configured? Written into ~/.codex/config.toml; declared in the permission section of .aic/.aicrc.

Who manages it? Permission panel.

What problem does it solve? Teams share one permission policy (e.g. “read-only mode”) instead of having each developer configure their own.

7. Provider profiles

What is it? A Provider profile is a different configuration variant of the same tool (different model, base URL, MCP set, etc.) that aic maintains and switches between.

Where is it configured? For OpenCode, switching copies opencode.json.<name> / opencode.jsonc.<name> into opencode.json / opencode.jsonc. Other tools follow similar patterns.

Who manages it? Provider panel (←/→ for sub-tabs, enter / s to switch).

What problem does it solve? Switch model / account / region without restarting the tool. Switching automatically backs up the previous config.

8. Registry cache

What is it? A local Git clone of aic-registry (the public Registry repository) that stores installable Skill / Context / MCP templates.

Where is it configured? ~/.aic/cache.

Who manages it? aic install / update / sync syncs the cache automatically; no manual intervention needed.

What problem does it solve? Decouples Skill / Context / MCP publishing from the aic binary. Templates can be updated independently of the aic core.

9. Link mode

What is it? Controls whether Skills link only into tool-specific directories or also into the shared .agents/skills/ directory.

isolated (default): links only into tool-specific directories (.claude/ / .codex/ / .gemini/ / .opencode/).
shared: also links into .agents/skills/.

Where is it configured? The link_mode field in .aic/.aicrc.

Who manages it? Ops panel (chosen during aic init) or CLI (aic init --link-mode shared).

What problem does it solve? Use shared when the team wants a unified format and any tool that understands .agents/ to work. Use isolated when each tool should maintain its own configuration (e.g. some teams run Codex on a different setup).

Embedded diagrams

The two diagrams below are rendered with Mermaid. The Registry data flow and Skill sync flow are referenced often, so they live here as embedded Mermaid:

flowchart LR
  REG[aic-registry<br/>GitLab / GitHub / Gitee]
  CACHE[~/.aic/cache<br/>local Git clone]
  AIDX[index.yaml]
  MGR[aic service layer]
  LINK[linker]
  PROJ[.aic/.aicrc<br/>project declaration]

  REG -->|git fetch| CACHE
  CACHE --> AIDX
  AIDX --> MGR
  MGR --> LINK
  MGR --> PROJ

flowchart LR
  SRC[Skill source<br/>~/.aic/cache/skills/&lt;name&gt;]
  AICRC[.aic/.aicrc]
  CLAUDE[.claude/skills/&lt;name&gt;]
  CODEX[.codex/skills/&lt;name&gt;]
  GEMINI[.gemini/skills/&lt;name&gt;]
  OPENCODE[.opencode/skills/&lt;name&gt;]
  AGENTS[.agents/skills/&lt;name&gt;]

  SRC -.->|isolated mode| CLAUDE
  SRC -.->|isolated mode| CODEX
  SRC -.->|isolated mode| GEMINI
  SRC -.->|isolated mode| OPENCODE
  SRC -.->|shared mode append| AGENTS

  AICRC -.records declaration.-> SRC

Diagrams are rendered client-side by src/components/MermaidInit.astro via mermaid.run; the dark theme follows system preference.