ido4

    Getting Started: Your First 10 Minutes with ido4

    Welcome to ido4! This guide will walk you through installing the CLI, running the initial setup, and launching your first interactive learning sandbox. By the end of this guide, you will have experienced the core ido4 workflow.

    1. Prerequisites

    Before you begin, make sure you have the following tools installed:

    • Node.js (v16.0.0 or higher)
    • npm (comes with Node.js)
    • Git
    • GitHub CLI (the gh command)

    AI Assistant Requirements

    ido4 is built and tested to work with specific AI coding assistants:

    • Claude Code (Primary) - Most mature integration and behavior
    • Gemini CLI (Secondary) - Supported with ongoing improvements

    Recommended Setup: Visual Studio Code with Claude Code extension, though ido4 is not limited to VSCode as your IDE. The CLI has been primarily tested and optimized for this configuration.

    Note: ido4 is under constant development with regular compatibility improvements across AI tools.

    Security and Privacy

    Data Privacy: ido4 CLI operates entirely locally and does not traffic any data from your repository to external servers. All repository code and project information remains on your local machine and your chosen GitHub repositories.

    Transparency: All git operations performed by ido4 are fully transparent and auditable. You can inspect every command and action the CLI takes with your codebase.

    If you don't have the GitHub CLI, install it with one of the following commands:

    # macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Ubuntu/Debian
sudo apt install gh

    2. Installation

    Install ido4 globally using npm. This makes the ido4 command available from anywhere in your terminal.

    npm install -g ido4

    To verify the installation, you can run:

    ido4 --version

    About the Methodology: ido4 implements the Hydro framework's core principles: waves replace time-boxes, dependencies drive flow, and AI classification optimizes human-AI collaboration. The CLI automates the coordination that makes this approach scalable.

    3. The Most Important Command: ido4 setup

    Before you can use ido4, you must run a one-time global setup. This command securely connects ido4 to your GitHub account and configures your AI assistant.

    1. Run the setup wizard:

      ido4 setup

    2. Authenticate with GitHub: The wizard will guide you through authenticating. We recommend using the Web Browser (OAuth) method for the best experience.

    3. Configure Your AI Assistant: The tool will scan your system to detect installed AI tools. Choose your preferred assistant from the list (Claude Code recommended for optimal experience).

    4. Set Sandbox Directory: When prompted, it's highly recommended to configure a directory for the learning sandboxes (the default ~/ido4-sandboxes is a great choice).

    This setup only needs to be done once.

    4. Your First Workflow: The Sandbox

    The best way to learn ido4 is by doing. The sandbox provides a safe, pre-configured project environment where you can learn the methodology without affecting any of your real projects.

    1. Launch the sandbox initializer:

      ido4 sandbox:init

    2. Choose a Scenario: You will be presented with a list of learning scenarios. For your first time, we recommend the data-explorer scenario. Select it from the list.

    3. Project Creation: The tool will now automatically:

      • Clone the scenario template from GitHub.
      • Create a new, private GitHub repository under your account.
      • Set up a local project directory.
      • Create all the necessary issues and a GitHub Project board.

      When it's finished, you will see a success message with the next steps.

    4. Start Your First Task:

      # Navigate into your new sandbox directory
cd ~/ido4-sandboxes/sandbox-data-explorer-YYYY-MM-DD

# Start the very first task!
ido4 task:start T.1

      This command will simulate the start of a development task, updating the status on your GitHub Project board and providing context for your AI assistant.

    🎉 Congratulations!

    You have successfully installed ido4, configured your environment, and started your first task in a wave-based workflow. You've experienced the core loop of the ido4 methodology.

    Next Step: Core Concepts: The ido4 Way