IWork Studio README

The safe way to let AI edit your Numbers, Keynote and Pages files.

Designed decks from your data and your brand, checked as rendered. Arabic-ready.
Every change is backed up, verified and undoable, and anything risky is refused, never guessed.

🛡️ Never damages your file	🎨 Designed from your data	ع Arabic first-class
Backup → change a copy → re-read and compare → atomic swap. Open files are left alone. One call undoes any change.	Turn a spreadsheet into a Keynote deck with chart and table slides in your brand kit, then review it as rendered.	Arabic and right-to-left text round-trip exactly, in every app and every export.

Install · Try it · Safety · What it can do · All tools · For AI agents · Changelog

_{15 seconds: data → designed deck → a safe rollback → Arabic. HD video}

_{▶ Watch the film with sound (46s) · Read the launch story}

Install

That's it. The installer sets up uv if needed, and uv brings its own Python.

• Fence it (recommended): … | sh -s -- --roots ~/Documents ~/Desktop limits it to those folders. Other clients: set IWORK_STUDIO_ROOTS (:-separated).
• Load less (optional): only work in Keynote? Set IWORK_STUDIO_TOOLSETS=keynote,design (any of files, numbers, keynote, pages, design; default all). Fewer tools keep the AI focused and its context small. The Claude Desktop extension has a Toolsets field; in Claude Code: claude mcp add iwork-studio -e IWORK_STUDIO_TOOLSETS=keynote,design -- uvx --from iwork-studio@latest iwork-studio-mcp. Capabilities, read, find, undo and the kit list always load.
• First run: macOS asks once whether Claude may control Keynote / Pages / Numbers. Click OK. (Missed it? System Settings → Privacy & Security → Automation.)
• Check it: ask "what can iwork-studio do on this Mac?".
• Remove: uvx --from iwork-studio@latest iwork-studio-mcp uninstall

AI agent setting this up for someone? Pick the row for their app, run it, then call iwork_capabilities. Rules for using the tools are in AGENTS.md.

Just ask, in English or Arabic

No file handy? Ask "copy the iWork Studio samples to my Desktop and turn sample-sales.numbers into a board deck". The samples are synthetic sales data with an English and an Arabic sheet.

"Build a 6-slide pitch deck for a solar-panel startup in the midnight kit, with speaker notes, and export it to PowerPoint."

"Turn sales.numbers into a board deck: chart the quarters, a table of the top regions, in our Acme kit."

"Take the fonts and colours from brand.key and save them as our Acme kit."

"Review pitch.key and fix anything that overflows or is too small to read."

"Make budget.numbers look professional with the banking kit — and show me a preview first."

"Turn sales.csv into a Numbers file, make the header bold on a teal fill, show column B as SAR with two decimals, and add a total row."

"In pitch.key, switch to the Gradient theme, make the title on slide 1 white at 60 pt, add a dissolve between every slide, and put logo.png on the last slide."

"Add a bar chart of revenue by quarter for 2025 and 2026 to slide 4."

"Duplicate slide 3, move the copy to the front and add presenter notes: ملاحظات المتحدث"

"Fill the Name and Date fields in offer-letter.pages, then export it as a password-protected PDF."

"In the invoice.pages table, set the quantity in B3 to 12 and make D9 the total of D2:D8."

"Find my Keynote decks from this week and export each one to PowerPoint."

"Undo the last change to budget.numbers."

What it can do

⚡ = works anywhere, no app needed (pure Python). Everything else drives the real app on a Mac with a logged-in session, classic iWork or the Creator Studio apps.

Every file type: preview any change before it's made (dry_run), look up metadata, pull the preview thumbnail, find files with Spotlight, check that a word is visibly rendered, check the rendered font/size/colour, list backups and undo.

What it won't do

On purpose, so it never breaks a file:

• Files with charts are refused by the tools that work without the app: their rewrite can silently break a chart's link to its data. The app-driven tools (Keynote slides, theming, transitions, images; Numbers formulas and sort) work on them and check every chart is still there.
• Charts in Numbers and Pages aren't created: they aren't reliably scriptable, and we refuse rather than click through the app's menus and risk your file. Keynote charts can be added. To chart sorted data without touching a Numbers chart, sort into a new table (numbers_sort with to_new_table) and build a Keynote chart slide from it.
• Pages is limited to text and existing tables: replace, set body, placeholders and table cells. New tables can't be created (Pages 15 doesn't script it), and page-layout documents, like most letter templates, have no body text. There is no Pages file format parser anywhere, so it doesn't fake one.
• Formulas and row shifts: in a table that has formulas, rows and columns can only be appended without the app. Inserting in the middle would leave references pointing at the wrong cells.
• Not scriptable by Apple, so not offered: Numbers table styles, Keynote shape fill and text alignment, deleting a Keynote table, editing a theme's master slides. Page margins and page setup are planned.

Designed, not just edited

Six design kits turn a plain deck or table into something you'd present: a font pair (Latin + Arabic, all bundled with macOS — nothing to install), a restrained palette checked for WCAG contrast, and a type scale.

Build with one (keynote_build_deck(..., kit="midnight")), restyle anything (keynote_apply_design, numbers_apply_design), or bring your brand as colours and fonts — contrast is checked. Agents also get a design guide: one idea per slide, titles that state the takeaway, right-aligned numbers, restrained colour.

Your brand, once. Point iwork_extract_design_kit at a deck or table that already has your look: it reads the fonts (Latin and Arabic) and colours, and saves them as a named kit you can use anywhere a kit goes. Or save your colours and fonts directly with iwork_save_design_kit.

Numbers on slides. A slide in keynote_build_deck can carry a chart or a table, from data or straight from a Numbers table: the header row gives the columns, the first column the rows. Tables get the kit's header band, fonts, banding and right-aligned numbers, and every cell is read back.

It checks its own work. keynote_review_deck renders the deck through Keynote and compares every drawn line with its text box: text off the slide or running past its box is an error; text Keynote had to shrink to fit, overlapping boxes, text under 18 pt and crowded slides are warnings. keynote_slide_image hands a slide back as an image, so an agent can look before it says "done".

The safety model

An iWork app will happily say "saved" about a file it just broke. Nothing here trusts "saved".

backup → change a scratch copy → re-open it and compare → atomic swap
                       ↘ anything off: your file is untouched, the error says why

• Backup first, versioned and private: in ~/.iwork-studio/backups/ (or IWORK_STUDIO_BACKUP_DIR), never beside your file, so backups don't fill or sync your iCloud Desktop and Documents. The last 10 per file are kept.
• Never behind the app's back: if the file is open in Numbers, Keynote or Pages, the write is refused. The app's next save would quietly overwrite the change.
• Re-read and compared: exactly the requested change happened, and nothing else did. A cell edit reads the edited cell back and checks every other cell. A row insert checks every cell at its new position. A slide op checks every other slide. A sort checks it's a pure reorder, and refuses up front when the table's formulas read other rows (Numbers' own sort would break them). On files with charts, every chart is counted before and after; on decks with tables, every table's cells are compared. An export is read back with a second, independent tool.
• Atomic swap: the file is replaced in one step, so a crash can't leave half a file.
• The app's "ok" is never trusted. App-driven writes are re-read from disk, and a write that "succeeded" but didn't land is rolled back.
• Undo is one call: iwork_list_backups → iwork_restore_backup. The restore backs up the current version first, so undo can be undone too.
• Preview first: every write that changes an existing document takes dry_run=true (restore and export are the exceptions). It runs the real change on a throwaway copy, with every check, and shows exactly what would change. Your file isn't touched.
• Find and replace keeps formatting: in Pages, only the paragraphs that contain the text are rewritten.
• New files never overwrite an existing one.
• Refuse, don't mangle. The worst case is a clear "no", never a broken file.

Arabic & RTL

• Arabic text round-trips exactly in all three apps, including presenter notes, Pages placeholders and Pages table cells.
• Paragraph direction is checked in Pages. A replace that flips a right-to-left paragraph to left-to-right is rolled back. Pages writes new paragraphs left-to-right, even Arabic ones, and scripting can't change that, so those are flagged: set the direction in Pages (Format › Text).
• Values are kept as typed: Arabic-Indic digits (١٢٣), "$1,234.56" and =… text stay text. Pass a real number when you want a number.
• When checking a rendered PDF, assert one Arabic word. PDF text layers reorder multi-word RTL text.

All 65 tools

Writes are marked destructive and reads read-only, so clients can ask before writing. Every write that changes an existing file takes dry_run=true for a preview. Every tool has a title, every parameter a description, and every tool says when to use it instead of its siblings. Need fewer? Load only some toolsets (see Load less under Install).

Keynote slide, theme, transition and image tools refuse a deck that's open in Keynote (they never close a window that may hold unsaved work). To hide them all: IWORK_STUDIO_DISABLE_SLIDE_OPS=1.

Prompts. Clients that show MCP prompts get four ready-made workflows: Pitch deck from an outline, Report deck from a Numbers table, Restyle with my brand and Make this table look designed. Each writes to the design rules, builds in one call, previews before restyling, and runs the design review before it calls the job done.

For AI agents

• AGENTS.md: setup and usage rules for any agent (Codex, Cursor, Copilot, Gemini; Claude Code reads it via CLAUDE.md).
• MCP instructions: the server sends its rules on connect, so the model has them even without this repo.
• Skill: skill-pack/SKILL.md, auto-discovered by Claude Code in this repo, or bash skill-pack/install.sh for other skill-based agents. It includes CLI scripts with JSON output for agents without MCP.
• llms.txt: a short machine-readable summary.

The contract: JSON in, JSON out. Errors are typed and say what to tell the user: ChartRefusalError, DocumentOpenError, PagesOutOfScopeError, AquaSessionError (no Mac GUI here) and so on. Don't retry a refused write with a trick.

Python

pip install iwork-studio      # Python 3.12

from iwork_studio import numbers_structure, numbers_format, numbers_io, keynote_io, keynote_slides, exporter, backups

from iwork_studio import keynote_deck, design, review

keynote_deck.build_deck("pitch.key", [{"title": "شمس", "body": "Clean energy for every home"},
                                      {"title": "Why now", "body": ["Trust", "Access"]},
                                      {"title": "Riyadh leads growth", "chart": {"type": "bar", "from": "sales.numbers"}}],
                        kit="midnight")                                  # macOS + Keynote
review.review_deck("pitch.key")["findings"]                              # macOS + Keynote
design.extract_kit("brand.numbers", name="Acme", save=True)
numbers_structure.import_csv("sales.csv", "sales.numbers")
design.apply_to_numbers("sales.numbers", "banking")
numbers_format.set_cell_style("sales.numbers", "A1:D1", bold=True, fill_color="#1A7F79", font_color="#FFFFFF")
numbers_format.set_number_format("sales.numbers", "B2:B99", "currency", currency_code="SAR", decimal_places=2)
numbers_io.edit_cell("sales.numbers", "B2", 2500)
keynote_io.edit_text("pitch.key", "2025", "2026")
keynote_slides.set_presenter_notes("pitch.key", 1, "ملاحظات")          # macOS + Keynote
exporter.export("pitch.key", "pptx")                                     # macOS + Keynote
backups.restore_backup("sales.numbers", backups.list_backups("sales.numbers")[0]["name"])

pure Python file parsers (headless, deterministic)  →  .numbers everything, .key text
the real app via AppleScript / JXA                   →  .key slides & theming, .pages text & tables, formulas, sort, export, render checks
MCP server · CLI scripts · skill                     →  thin wrappers over the same library and the same safety model

src/iwork_studio/   numbers_io · numbers_format · numbers_structure · keynote_io · keynote_slides · keynote_theme
                    keynote_deck · keynote_table · design · review · preview · pages_io · app_ops · exporter
                    helpers · format_check · render_verify · pdf · backups · apps · mcp_server
mcpb/               Claude Desktop extension manifest (scripts/build_mcpb.sh builds the .mcpb)
skill-pack/         SKILL.md · CLI scripts · references (capabilities, traps, pins); also the Claude Code plugin
.claude-plugin/     plugin marketplace (one plugin: skill-pack/)
tests/              headless suite (CI) · `pytest -m aqua` = live suite for a Mac with iWork
install.sh          one-line setup for the Claude desktop app

Contributing

git clone https://github.com/Arkanji/iwork-studio.git && cd iwork-studio
uv run --extra test pytest -m "not aqua"      # headless suite, what CI runs
uv run --extra test pytest -m aqua            # live suite: a Mac with Numbers, Keynote and Pages
scripts/live.sh                               # the same, unattended: logs to ~/.iwork-studio/probes, quits the apps it opened

iWork changes between releases. If something breaks, check the capabilities and traps, run the live suite, and pin what changed. New write routes must follow the safety model and come with tests that prove the rollback. Clone outside iCloud-synced folders.

License

MIT, traps included. Take them.