DOCSEARCHbyAlgolia
Submit Docs

AiMaMi Documentation

repository·main·Indexed 23 days ago

https://github.com/borawong/aimami

A native desktop companion for OpenAI Codex (version 1.0.0) that provides a graphical interface to manage accounts, sessions, MCP entries, and smart routing. It simplifies workflows by managing local configuration files (JSON, TOML, SQLite) in ~/.codex, offering features like automatic account switching, relay management, and custom instruction handling. Built with React and Tauri, it supports macOS, Windows, and Linux.

Tokens
15.7K
Snippets
27
Records
94
Agent score
80%

What's inside AiMaMi

  1. Overview of AiMaMi

    main

    AiMaMi is a native desktop companion for OpenAI Codex designed to unify the management of accounts, routing, sessions, and local configurations. It replaces manual editing of TOML, JSON, and SQLite files located in ~/.codex with a graphical interface.

    Key capabilities include:

    • Account Management: Switch between multiple accounts without manually editing auth.json.
    • Automatic Switching: Automatically finds and switches to an available account when a quota limit is reached.
    • Smart Routing: Enables the use of proxy/third-party models within the Codex desktop environment while attempting to preserve chat history.
    • Session Management: View, statistically analyze, and batch clean local threads based on real indices.
    • MCP / Skills Management: Graphical management of MCP entries and Skills lifecycles, including backup and recovery.
    • Custom Instructions: Manages controlled blocks within ~/.codex/AGENTS.md with preview and rollback support.
    • System Maintenance: Tools for diagnostics, cleaning, rebuilding the registry, force-killing Codex, and fixing configuration issues.

  2. Overview of AiMaMi core capabilities

    main

    AiMaMi is a native desktop companion for OpenAI Codex designed to manage local configuration files located in ~/.codex. It provides a UI for high-frequency workflows that would otherwise require manual editing of TOML, JSON, and SQLite files.

    Key modules include:

    • Account management: Switch accounts via auth.json, view quotas, and import/export accounts.
    • Auto-switch: Automatically handles fallback when quotas (5-hour or weekly) are exhausted.
    • Smart router: Allows using relay models inside Codex Desktop while keeping historical threads resumable. Note: Relay models are forwarded through AiMaMi's local proxy; AiMaMi must remain running for this to work.
    • Relay management: Setup providers, run connectivity tests, and perform router diagnostics.
    • Session management: Inspect, analyze, and bulk-clean local threads.
    • MCP / Skills: Manage the lifecycle of MCP entries and Skills with backup/restore capabilities.
    • Custom instructions: Manage the AiMaMi-managed block within ~/.codex/AGENTS.md with preview and rollback features.
    • System maintenance: Diagnose issues, clean/rebuild registry, and force-quit Codex.

  3. Configure Niu Image Gen parameters

    main

    Niu Image Gen uses a hierarchy for parameter resolution:

    1. Explicit Flags: Command-line flags (e.g., --quality 4K --ratio landscape) always take the highest priority and override all other settings.
    2. Saved Config: If no explicit flags are provided, the script uses the values stored in quickMode or batchMode configurations.
    3. Hardcoded Defaults: If no configuration is found, the script falls back to hardcoded defaults (2K quality, square ratio).

    Note: quickMode and batchMode configurations are independent. Changing one does not affect the other.

  4. Initialize Niu Image Gen via Entry Logic

    main

    Before performing any action with the niu-image-gen plugin, you must first check the current configuration state by running the --get-config command. This determines whether the user needs to go through the First-time Wizard, Quick Mode Setup, or if they can proceed directly to generation.

    Decision Logic Flow:

    1. If hasKey is false $\rightarrow$ Run First-time Wizard.
    2. If hasKey is true but quickMode is null $\rightarrow$ Run Quick Mode Setup.
    3. If user intent is to modify settings $\rightarrow$ Run Modify Config.
    4. If user intent is batch generation $\rightarrow$ Run Batch Mode.
    5. If user intent is to edit an existing image $\rightarrow$ Run Edit Image.
    6. If quickMode exists and a prompt is provided $\rightarrow$ Run Quick Mode.
    7. Otherwise $\rightarrow$ Provide Help.
    node "$SCRIPT" --get-config

  5. Understand the AiMaMi architecture

    main

    AiMaMi operates as a bridge between a React-based user interface and the local Codex data. The architecture follows this flow:

    1. React UI: The frontend layer.
    2. invoke(): The bridge used to call Tauri commands.
    3. Tauri commands: The backend layer that executes logic.
    4. Core: The logic layer that interacts with:
      • ~/.codex: The native Codex configuration and data.
      • ~/.codex/codexmate/: The specific application data for AiMaMi.
    5. Platform layer: macOS or Windows specific implementations.

  6. Use Niu Image Gen in Batch Mode

    main

    Batch mode allows for generating multiple different images from multiple prompts in parallel.

    1. Configuration

    Before running a batch, ensure your batch configuration is set. You can check your current settings using --get-config. If batchMode is not configured, you must set the quality, ratio, and concurrency using:

    node "$SCRIPT" --set-batch-mode --quality <Q> --ratio <R> --concurrency <N>

    Concurrency levels:

    • 1~2: Stability priority 🛡️
    • 3: Recommended (balance of speed and stability) ⚖️
    • 5~10: High-volume fast generation 🚀

    2. Execution Methods

    Inline Prompts (for a small number of prompts provided directly):

    node "$SCRIPT" --batch-inline "<p1>" "<p2>" "<p3>" [--quality Q --ratio R --concurrency N]

    File Prompts (for larger batches using a JSON file containing a string array of prompts):

    node "$SCRIPT" --batch <file.json> [--quality Q --ratio R --concurrency N]

    3. Constraints

    • Maximum batch size: 20 prompts per run.
    • Maximum concurrency: 10.
    • Output directory: Default is ~/Pictures/niu-image-gen/.
    node "$SCRIPT" --set-batch-mode --quality <Q> --ratio <R> --concurrency <N>

  7. Quick Start: Install and Run AiMaMi

    main

    To run AiMaMi in development mode, ensure you have Node.js, pnpm, Rust, and the required Tauri system dependencies installed. Follow these steps:

    1. Clone the repository.
    2. Install dependencies using pnpm.
    3. Run the development environment using pnpm tauri dev.

    For production builds, use pnpm tauri build after verifying the frontend and Rust code.

    git clone https://github.com/borawong/AiMaMi.git
cd AiMaMi
pnpm install
pnpm tauri dev

  8. Build Commands for AiMaMi

    main

    Use the following commands to verify and build the project:

    • pnpm build: Performs a frontend build check.
    • cargo check --manifest-path src-tauri/Cargo.toml: Performs a Rust code check.
    • pnpm tauri build: Creates a production build.
    pnpm build                                      # 前端构建检查
cargo check --manifest-path src-tauri/Cargo.toml  # Rust 检查
pnpm tauri build                                # 生产构建

  9. Modify existing Niu Image Gen configuration

    main

    To change settings for Quick Mode, Batch Mode, or the API Key, first retrieve the current configuration using --get-config.

    Users can then choose to:

    1. Modify Quick Mode: Re-run the quality, ratio, and count selection steps.
    2. Modify Batch Mode: Configure batch-specific parameters (quality, ratio, concurrency).
    3. Update API Key: Provide a new key using --set-key <NEW_KEY>.
    node "$SCRIPT" --get-config

  10. Build AiMaMi for production

    main

    Use the following commands to verify the frontend and Rust code, or to generate a production build of the application.

    pnpm build                                        # Frontend build check
cargo check --manifest-path src-tauri/Cargo.toml  # Rust check
pnpm tauri build                                  # Production build

  11. Edit images with Niu Image Gen

    main

    You can modify existing images by providing an edit instruction (e.g., "change background to seaside"). The tool supports three distinct edit modes based on your intent:

    Mode A: Multi-source batch edit

    Use this when you have multiple different source images and want to apply the same edit instruction to all of them.

    node "$SCRIPT" --edit --image "<path1>" --image "<path2>" --image "<path3>" --prompt "<edit instruction>" [--quality Q] [--ratio R] [--concurrency N]

    Mode B: Multi-variation edit

    Use this when you have one source image and want to generate multiple different versions of the same edit (e.g., "give me 3 variations").

    node "$SCRIPT" --edit --image "<image_path>" --prompt "<edit instruction>" --count <N> [--quality Q] [--ratio R]

    Note: --count defaults to 2, maximum is 4.

    Mode C: Single edit

    Standard mode for applying one edit to one image.

    node "$SCRIPT" --edit --image "<image_path>" --prompt "<edit instruction>" [--quality Q] [--ratio R]

    Usage Notes

    • Image Selection: You can provide a file path, drag an image into the chat, or reference previous generations in the conversation.
    • Iterative Editing: You can continue editing a result by providing a new instruction; the tool will use the newly edited image as the new source.
    node "$SCRIPT" --edit --image "<image_path>" --prompt "<edit instruction>" --count <N> [--quality Q] [--ratio R]