@atollhq/skill-codex

Install the Atoll project management integration for Codex CLI.

Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, milestones, comments, and webhooks on Atoll — the same API surface a human teammate uses.

Install

npx @atollhq/skill-codex --profile agent-a --key sk_atoll_... --org your-org-id --project project-id --team team-id
# or
ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex

Optional defaults: --project, --team, and --base-url are stored with the selected mode. Use --no-project, --no-team, or --no-base-url to clear previously saved defaults. When --profile is set, credentials and defaults are stored only in that named Atoll CLI profile. The installer does not write global ATOLL_* exports to ~/.zshrc or ~/.bashrc. Use atoll --profile agent-a ... for profile-scoped commands, or omit --profile to use env-var mode.

Get an API key from Settings > Members > Add Agent (or Create API Key for integrations) in the Atoll app.

This does five things:

1. Installs the atoll-api skill to ~/.codex/skills/atoll-api/
2. Appends (or updates) an # Atoll Integration section in ~/.codex/AGENTS.md
3. Copies API reference files to ~/.codex/atoll-references/
4. Creates or updates the named Atoll CLI profile when --profile is provided
5. Appends Atoll env var exports to your shell profile (~/.zshrc or ~/.bashrc) only when no profile is provided

For profile mode, Codex has the Atoll skill immediately and terminal commands can use atoll --profile agent-a .... For env-var mode, open a fresh shell or source your profile.

Using the integration

Once installed, ask Codex anything task-related:

"List my Atoll tasks"
"Create an issue to fix the login bug, priority 1"
"What goals are off pace?"
"Check my Atoll heartbeat"
"Move ATOLL-42 to in_progress"

Companion CLI

For terminal-first work, see @atollhq/cli:

npm install -g @atollhq/cli
atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --team team-id
atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --no-team --no-base-url
atoll heartbeat
atoll issue list --json
atoll agent-context

For multiple agents or orgs, use CLI auth profiles:

atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid
atoll auth login --profile agent-b --key sk_atoll_... --org-id org-uuid --project project-id --team team-id
atoll --profile agent-b issue list

Always persist --org-id on named profiles, or pass --org-id per command. Resource commands fail when the selected profile has no org ID so agents do not accidentally operate with the wrong scope.

The companion CLI also supports safer issue removal and upstream feedback with local retry drafts:

atoll issue archive ATOLL-42
atoll issue delete ATOLL-42 --dry-run
atoll feedback "The heartbeat output should include blocked issue details"

License

MIT