@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

Install or refresh the local skill files without configuring credentials:

npx --yes @atollhq/skill-codex@latest

Bare invocation and --install-only only update ~/.codex/skills/atoll/, the profile-neutral routing hint, and compatibility references. They do not inspect or change Atoll credentials, profiles, shell files, or repo configuration, even when ATOLL_* variables are present.

Configure a named profile explicitly:

npx --yes @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-id --team team-id

For intentional environment configuration, use --configure:

ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid npx --yes @atollhq/skill-codex@latest --configure

Configuration mode supports --project, --team, and --base-url. Use --no-project, --no-team, or --no-base-url to clear saved defaults. Pass --profile to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global ATOLL_* exports in profile mode. Use atoll --profile agent-a ... for profile-scoped commands.

For multi-org setups, keep global Codex instructions neutral and bind profiles per repo:

npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-org-id \
  --write-project-instructions --project-dir /path/to/repo --instruction-files agents,claude

--write-project-instructions writes a small managed block to repo-local instruction files. It requires --profile, defaults to the current directory, writes AGENTS.md by default, and can also write CLAUDE.md with --instruction-files agents,claude. If the target file already has unmanaged Atoll profile guidance, pass --force-project-instructions after reviewing the replacement.

Get an agent API key from Agents in the Atoll app. Integration keys are managed from Settings > Integrations.

Every invocation installs the local skill assets, routing hint, and compatibility references. Configuration mode additionally:

1. Installs the atoll skill to ~/.codex/skills/atoll/
2. Appends (or updates) a small profile-neutral Atoll skill routing hint 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) when --configure is used without a profile
6. Optionally writes repo-local profile guidance when --write-project-instructions is provided

For profile mode, Codex has the Atoll skill immediately, global Codex guidance points to that skill without embedding the full Atoll guide, and terminal commands can use atoll --profile agent-a .... For explicitly requested env-var mode, the installer writes ATOLL_ENV_MODE=1 with the credential exports; open a fresh shell or source your profile.

Use @latest in the npx command so npm does not reuse a stale cached installer. In profile mode, the installer prints its package version and a verification command; run atoll --profile agent-a agent-context --json if you need to confirm the profile was created.

The installer writes credential-bearing files atomically, refuses symbolic-link targets, uses 0600 for credential files, and uses 0700 for dedicated credential directories. Concurrent installer runs are serialized, and env-var mode shell-quotes every value written to the shell 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 --profile agent-a heartbeat
atoll --profile agent-a issue list --json
atoll --profile agent-a 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