CLI / Use with AI agents
Use Workspark with AI agents
Give Claude, Codex, or OpenCode grounded access to your Workspark data. Your agent can log accomplishments, help you prep a self-review, check on your OKRs, and read your org data, all from real output, never fabricated.
What you need
Two pieces work together to connect an agent to Workspark.
The CLI
ws
A single binary that talks to Workspark. The grounded connection, the agent's hands.
The Skill
workspark/skills
Instructions that teach the agent to drive ws correctly. The agent's playbook.
How you install the two pieces depends on your agent. Jump to your path:
Claude
Easiest — CLI + Skill in one pluginOn Claude, a single plugin bundles both the ws binary and the Skill. Nothing else to install.
Download and upload the plugin
Download the Workspark plugin file, then upload it into Claude. One-click install from the Workspark marketplace is coming soon.
Upload it into Claude (desktop app / Cowork)
- Open Customize then Personal plugins.
- Click the + button.
- Choose Create plugin then Upload plugin.
- Select the
workspark-0.2.2.pluginfile you just downloaded.
Allow network egress to Workspark (required in Cowork)
The wsbinary runs inside Claude's sandbox, which blocks outbound network connections by default. Without allowlisting Workspark's domains, the CLI cannot reach the API and every command will fail with a network error.
In Claude settings, go to Settings then Capabilities then Allow network egress. Turn the toggle on. Then, under Domain allowlist and Additional allowed domains, add both of these:
app.workspark.ioworkspark.ioSecurity note:Claude's settings panel shows a caveat that network egress carries risk. Only add domains you trust.app.workspark.iois the Workspark API andworkspark.iocovers the sign-in flow.
Authenticate
The plugin's Skill installs the bundled ws binary automatically the first time Claude uses it. Then it needs to sign in to your Workspark account. Two flows: Claude Cowork in the sandbox, or Claude Code on your machine.
Claude Cowork
The Cowork sandbox can't open a browser, so Claude walks you through it. Just ask Claude to log in:
- Tell Claude “Log in to Workspark.”
- Claude gives you a URL. Open it on your own machine and approve the sign-in.
- Come back and tell Claude “continue” or “done”. Claude validates the session and you're ready to go.
The sign-in link expires after a few minutes. If it lapses, just ask Claude to start the login again.
Claude Code
Ask Claude to run auth. It calls ws auth login, which opens the browser on your machine to sign in. Just tell Claude “Log in to Workspark.”
Try it
Once authenticated, tell Claude what you want to do. Some prompts to start with:
- Log what I shipped today as an accomplishment.
- Help me prep my self-review for the current cycle.
- Which of my OKRs are stale?
- Who on my team has been most active this month?
Claude confirms before taking any write action and never fabricates accomplishment entries, review content, OKR updates, or survey responses. Everything it does is grounded in what the CLI actually returns.
Codex, OpenCode & other harnesses
Add both piecesFor any other agent, install the two pieces yourself: the CLI binary, then the Skill that teaches the agent to use it.
Install the CLI
Install the ws binary so the agent has something to call. The simplest option works on every platform:
npm install -g @workspark/cliPrefer a shell script, PowerShell, or manual binaries? See the Install the CLI guide for all options, plus how to authenticate and set your organisation.
Install the Skill
Add the Workspark Skill to your agent harness so it knows how to drive the CLI correctly. One command:
npx skills add workspark/skillsPrefer to browse it first? The Skill is open source at github.com/workspark/skills.
This installs the Workspark Skill for your harness, including supported agents such as OpenAI Codex and OpenCode. Once installed, the agent pulls in the Skill when you ask it to work with Workspark.