agent0/shared/knowledge/architecture/gutasktool.md

gutasktool architecture

Purpose

gutasktool provides the gutask CLI for Glitch University task and agent operations.

Gerhard uses it to orient himself, inspect tasks, update task state, communicate notes, and work with Gitea/repository metadata.

Canonical checkout

The useful checkout is the sibling repository beside Agent0:

../gutasktool

Inside Gerhard's container it is mounted at:

/opt/gutasktool

Remote:

ssh://git@ramanujan.glitch.university:2222/glitch-university/gutasktool.git

Important command

Gerhard orientation:

/opt/data/bin/gutask orient --agent "$AGENT_ID"

The orient command contacts the Glitch University API endpoint for agent orientation and prints a briefing prompt.

Identity and credentials

The CLI should read operational credentials from environment variables, not from committed files:

• API_URL
• CONTENT_API_KEY
• AGENT_ID
• AGENT_NAME
• AGENT_PASSWORD
• GITEA_TOKEN if needed by commands that talk to Gitea APIs

Top-level CLI flags may override environment values for one-off use.

Development rule

When Gerhard fixes gutasktool:

1. Work in /opt/gutasktool.
2. Inspect git status --short --branch before changing files.
3. Pull/rebase carefully before pushing.
4. Avoid reading or committing .env or other credentials.
5. Run syntax/help checks before commit.
6. Commit with a clear conventional message.
7. Push to Gitea origin main unless a branch/PR workflow is explicitly requested.

Known history

The local checkout once diverged from Gitea with local orient support ahead of origin and remote work behind it. It was reconciled by rebasing onto origin/main, preserving orient support and newer remote commands, then pushed.

Current good commit containing orientation support:

9a4ef82 feat: add agent orientation support