ClayCast
TenSpy-ai/claycast
Automação programática da API interna do Clay.com em Python
Ver no GitHubToolkit Python não-oficial para automação da API interna do Clay.com via cookie de sessão do navegador. Permite criar e modificar tabelas, colunas, rodar enriquecimentos e descobrir endpoints undocumentados através de um daemon Playwright que captura requisições ao vivo.
Instalação
npx convez-ai TenSpy-ai/claycast1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar e modificar estrutura de tabelas e colunas no Clay via código
- Automatizar enriquecimentos de dados em larga escala
- Exportar e importar schemas de tabelas entre workspaces
- Descobrir e reverter formato de endpoints undocumentados do Clay
Veredito

Ferramenta poderosa para quem precisa automatizar fluxos do Clay em escala, mas exige experiência Python e acesso a sessão de browser. Use com cautela: é unofficial, usa endpoints internos e custa créditos reais em execuções de enriquecimento.
README
A tradução para o português deste README ainda está na fila.
ClayCast
An unofficial Python toolkit for driving Clay.com's internal REST API using your browser session cookie.
ClayCast does the schema-level work the official Clay MCP connector can't: creating and modifying tables, columns, and action columns from code; running and waiting on enrichments; exporting/importing table schemas; and discovering undocumented action-input shapes by capturing live requests against the app.
It ships as a Claude Code skill (so an agent can use it directly), and the underlying ClayClient is a plain Python SDK you can import and use on its own.
⚠️ Unofficial — use at your own risk. ClayCast is not affiliated with, endorsed by, or supported by Clay. It drives undocumented internal endpoints that can change or break without notice, and it authenticates with your own browser session cookie. You are responsible for staying within Clay's Terms of Service and for any actions you run (enrichment runs cost real credits).
What it can do
- Schema operations — create/modify/clone tables, columns, formula columns, and action columns programmatically.
- Enrichment — trigger runs and wait for completion (
run_column,run_and_wait). - Export / import — serialize a table's column structure (the portable ClayPrint format) to copy or clone structure across tables; export rows to CSV/JSON; export whole workspaces.
- Discovery — a Playwright-based browser daemon (
clay_browser.py) that runs Clay with your session cookie and auto-captures everyapi.clay.comrequest/response, so you can reverse the shape of endpoints ClayCast doesn't wrap yet.
Install as a Claude Code skill
Claude Code auto-discovers skills placed under a skills/ directory. Install ClayCast at one of two scopes:
Global (available in every project on your machine):
git clone https://github.com/TenSpy-ai/claycast.git ~/.claude/skills/claycast
pip install -r ~/.claude/skills/claycast/references/requirements.txt
# For the browser/discovery daemon only:
playwright install
Project-level (only this project; commit it with the repo to share with your team):
# from your project root
git clone https://github.com/TenSpy-ai/claycast.git .claude/skills/claycast
pip install -r .claude/skills/claycast/references/requirements.txt
Either way the skill must end up at …/skills/claycast/ with SKILL.md at its root. Claude Code reads SKILL.md's front-matter and loads ClayCast automatically when a task matches it. Requires Python 3.10+.
Project-level beats global when two projects need different versions, or when you want the skill version-controlled alongside the project. Global is simplest for personal use across many projects.
Installed layout
claycast/ # ~/.claude/skills/claycast/ (or <project>/.claude/skills/claycast/)
├── SKILL.md # skill manifest + full capability map (what Claude loads)
├── README.md # this file
├── .gitignore
├── references/
│ ├── clay-api-reference.md # the underlying Clay endpoints ClayCast wraps
│ ├── action-registry.md # action-column input shapes + integration gotchas
│ ├── cookie-setup.md # how to grab & configure CLAY_SESSION
│ ├── feature-gaps.md # roadmap: what's missing / what to build next
│ ├── requirements.txt # Python dependencies
│ └── .env.example # CLAY_SESSION placeholder
└── scripts/
├── clay_client.py # the ClayClient SDK (authenticated REST client)
└── clay_browser.py # Playwright daemon for request-capture / discovery
Authentication
ClayCast authenticates with your Clay session cookie (claysession in your browser — grab it from DevTools → Application → Cookies; full steps in references/cookie-setup.md). Nothing is hardcoded and no cookie is stored in the repo.
It resolves the cookie in this order:
- The
CLAY_SESSIONenvironment variable — simplest, works from anywhere:export CLAY_SESSION='s%3A...your-cookie...' - Otherwise, the nearest
.envfile containingCLAY_SESSION=, found by walking up from your current directory to your project root (the walk stops at the first.git, your home dir, or/).
Activate it with a .env file
- Already have a
.envcontainingCLAY_SESSION=somewhere from your working dir up to your project root? You're done — nothing to do. - Otherwise, turn the bundled template into a real
.env:
Open the newcp references/.env.example .env # place it at your PROJECT root.env, set your cookie, and save:
ClayCast picks it up on the next run.CLAY_SESSION=s%3A...your-cookie-value...
⚠️
references/.env.exampleis only the format template. Copy it out to a.envthat sits on the walk-up path — your project root (or your clone's root if you run ClayCast standalone). Just renaming it in place insidereferences/won't be found: the loader searches up the directory tree from where you run it, not inside the skill's own folder..envis gitignored — never commit it.
Use it directly from Python
You don't need Claude Code to use the client — point Python at the scripts/ dir and import it:
import sys; sys.path.insert(0, "scripts") # or .../skills/claycast/scripts
from clay_client import ClayClient
clay = ClayClient() # reads CLAY_SESSION from env / .env
table = clay.create_table(workbook_name="My Workbook", table_name="Leads")
clay.create_formula_column(table["tableId"], name="Domain", formula='...')
Documentation
| Doc | What's in it |
|---|---|
SKILL.md | Full capability map + design principles (also the Claude Code skill manifest). |
references/clay-api-reference.md | The underlying Clay endpoints ClayCast wraps (URLs, payloads, response shapes). |
references/action-registry.md | Action-column input shapes and integration gotchas. |
references/cookie-setup.md | Getting and configuring CLAY_SESSION. |
references/feature-gaps.md | Roadmap — capabilities not yet built, tiered by impact. Start here if you want to contribute a feature. |
Contributing
Issues and pull requests are welcome — ClayCast wraps a moving, undocumented API, so there's always more to wrap.
Start with the roadmap
references/feature-gaps.md is the best place to find something worth building. It's a living gap list of capabilities ClayCast doesn't implement yet, tiered by impact (Tier 1 = actually blocks common headless workflows), and most gaps come with a proposed method signature so a new wrapper slots into the SDK's existing conventions. Skim the open tiers, pick a gap, and you have a scoped first PR. The "Recently closed" section at the top shows the cadence and the shape a finished contribution takes.
For anything substantial, open an issue first so we can agree on the approach before you build.
Fork & PR workflow
# 1. Fork the repo on GitHub — the "Fork" button on github.com/TenSpy-ai/claycast
# 2. Clone YOUR fork
git clone https://github.com/<your-username>/claycast.git
cd claycast
# 3. Track upstream so you can stay in sync
git remote add upstream https://github.com/TenSpy-ai/claycast.git
# 4. Branch for your change
git checkout -b feature/views-crud # e.g. tackling feature-gaps Tier 1 #1
# 5. Install deps and point CLAY_SESSION at YOUR OWN workspace (see Authentication)
pip install -r references/requirements.txt
cp references/.env.example .env # then set your cookie; .env is gitignored
# 6. Make the change, test it against your own Clay workspace
# 7. Commit and push to your fork
git commit -am "Add views CRUD (feature-gaps Tier 1 #1)"
git push origin feature/views-crud
# 8. Open a PR: <your-username>:feature/views-crud -> TenSpy-ai:main
Before opening (or updating) a PR, sync your fork with git fetch upstream && git merge upstream/main.
Ground rules for PRs
- Never commit secrets or workspace data. Your
.envandCLAY_SESSIONcookie stay local (both gitignored). In any "verified live" comment, doc, or example, use a placeholder workspace id (e.g.12345) and placeholder table/field/audience ids — never your real ones. - Show how you verified an endpoint. These are internal endpoints, so note how you confirmed the request/response shape —
scripts/clay_browser.pycaptures liveapi.clay.comtraffic for exactly this. Date your "verified live" comments like the existing code does. - Match the conventions already in
clay_client.py— the proposed signature infeature-gaps.md, the return shapes, the two-step record-write pattern, and credit-cost callouts on anything that runs. - Mind the credits. Anything that triggers a run costs real Clay credits — guard it and document the cost; don't run it implicitly.
License
MIT © 2026 TenSpy-ai