Theia AI beginner guidance

[TheMatthew]

Bug Description:

New users and cross disciplinary ones have issues with setting up theia ai.

Issues found:

• How do I set up an API key?
• How do I know which model works for tooling?
• How do I get to the AI configuration view?
• What's the difference between AI configuration and AI settings
• Why can't I enter my API key in the AI configurations view?

Matthew's suggestions:

• Set up personas for a UX study, have users of varying skill.

From a technical point of view:

• Consider making the backlinks as the AI Config and AI settings from chat more visible, views are so coupled. as well, it is not obvious to new users to click on the ... menu to get info.

• As of today (dec 11) we have 51 settings in the AI Features. New users will be overwhelmed.

• The agents panel is the first one shown. It was a challenge to explain the link between agents, models and aliases. The menu really shows the what... but not the "why".

• Regarding API tokens, it would be good to have an API token widget that could automatically add the token to your environment. It could be a button that appears over the textbox.

function envVarExistsInProfile(profilePath: string, varname: string): boolean {
    if (!fs.existsSync(profilePath)) return false;

    const content = fs.readFileSync(profilePath, "utf-8");
    const regex = new RegExp(`export\\s+${varname}=`, "i");
    return regex.test(content);
}

function setEnvVariable(varname: string, value: string) {
    const platform = os.platform();

    // --- Windows environment variable check ---
    if (platform === "win32") {
        const current = process.env[varname];
        if (current) {
            console.log(`⚠ ${varname} already exists in your environment.`);
            const action = prompt("Overwrite? (y/n): ").trim().toLowerCase();
            if (action !== "y") {
                console.log("Skipping.");
                return;
            }
        }

        console.log(`Setting Windows environment variable: ${varname}`);
        execSync(`setx ${varname} "${value}"`);
        console.log("✔ Windows environment variable saved.");
        return;
    }

    // --- macOS + Linux ---
    const shell = process.env.SHELL || "";
    let profile = path.join(os.homedir(), ".bashrc");

    if (shell.includes("zsh")) {
        profile = path.join(os.homedir(), ".zshrc");
    }

    // Check current session env
    if (process.env[varname]) {
        console.log(`⚠ ${varname} is already set in current environment.`);
        const action = prompt("Overwrite? (y/n): ").trim().toLowerCase();
        if (action !== "y") {
            console.log("Skipping.");
            return;
        }
    }

    // Check profile file for existing setting
    if (envVarExistsInProfile(profile, varname)) {
        console.log(`⚠ ${varname} already exists in ${profile}.`);
        const action = prompt("Overwrite entry in file? (y/n): ").trim().toLowerCase();

        if (action !== "y") {
            console.log("Skipping.");
            return;
        }

        // Remove old lines for that variable
        const content = fs.readFileSync(profile, "utf-8")
            .split("\n")
            .filter(line => !line.includes(varname));
        fs.writeFileSync(profile, content.join("\n") + "\n");
    }

    const exportLine = `export ${varname}="${value}"`;

    // Append new value
    fs.appendFileSync(profile,
        `\n# Added by multi_api_keys.ts\n${exportLine}\n`
    );

    console.log(`✔ Added ${varname} to ${profile}`);
    console.log(`➡ Run: source ${profile}`); 
}

Steps to Reproduce:

1. Find a new user, preferably embedded or not pure software
2. Have them try to configure theia.ai

Additional Information

• Operating System: Any
• Theia Version: latest (1.60+)

[tfroment]

Thanks for sharing it @TheMatthew, I will also try to gather feedback from my experimentation in a dedicated issue (I am the "perfect" Theia AI dummy ;-))

[TheMatthew]

First step in a journey is always the most important!

[JonasHelming]

@ndoschek

[ndoschek]

Thanks a lot for the detailed feedback and suggestions @TheMatthew!

You're raising some very valid points especially around onboarding and overall UX clarity. We've already started making small improvements in the AI Chat view to help guide first-time users to setup language model providers, which will be available in the upcoming IDE version.

But I will review this in more detail and likely break it down into actionable sub-issues to better track improvements. Thanks again for your input, it's very helpful for shaping the next steps!