Contributing

Set up the SDK repository, run the three test tiers, and open a pull request.

The SDK is open source at github.com/Cycls/cycls under the MIT license.

Set up

git clone https://github.com/Cycls/cycls
cd cycls
uv sync --group test

Run the in-repository CLI with uv run cycls ... so you exercise your working tree rather than an installed release.

Run the tests

Three tiers.

Mocked

The default. No API calls, no Docker, about two minutes.

uv run pytest tests/
uv run pytest tests/agent/ -v

Live

Hits real provider APIs. Needs ANTHROPIC_API_KEY and skips silently without one.

set -a && source .providers.env && set +a
uv run pytest tests/agent/scenarios/test_live.py --live -v

Front end

cd client
npm test
npm run test:watch

Function tests need Docker running.

Repository layout

cycls/
  cli.py            the CLI
  _function/        Function, Image, Volume, Cron, remote
  _app/             App, auth, DB, sandbox
  _agent/           Agent, harness, tools, web
docs/               reference documents
examples/           runnable examples
tests/              mirrored to source
client/             the chat front end

Open a pull request

1. Fork the repository and create a branch.
2. Make the change, and add tests beside the code they cover.
3. Run uv run pytest tests/ and the front-end tests when you touch client/.
4. Push and open a pull request against main.

What helps most

• Bug reports with a minimal reproduction.
• Examples that show a real pattern end to end.
• Documentation fixes, including anything on this site that is wrong or unclear.
• Provider adapters. Adding one means a single file that conforms to the Provider protocol. See Custom loops.