iWork Studio

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).
• 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 git+https://github.com/Arkanji/iwork-studio 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

"Build a 6-slide pitch deck on programmable gift cards 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 Resal kit."

"Take the fonts and colours from brand.key and save them as our Resal 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 can't be created: Apple doesn't make them scriptable. Keynote charts can be added.
• 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, next to the file in <file>.backups/.
• Re-read and compared: exactly the requested change happened, and nothing else did. A cell edit 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. 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 takes dry_run=true. It runs the real change on a throwaway copy, with every check, and shows exactly what would change. Your file isn't touched.
• 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 64 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.

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": "Programmable value"},                                      {"title": "Why now", "body": ["Trust", "Access"]},                                      {"title": "Riyadh leads growth", "chart": {"type": "bar", "from": "sales.numbers"}}],                        kit="midnight")                                  # macOS + Keynotereview.review_deck("pitch.key")["findings"]                              # macOS + Keynotedesign.extract_kit("brand.numbers", name="Resal", 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 + Keynoteexporter.export("pitch.key", "pptx")                                     # macOS + Keynotebackups.restore_backup("sales.numbers", backups.list_backups("sales.numbers")[0]["name"])

pure Python file parsers (headless, deterministic)  →  .numbers everything, .key textthe real app via AppleScript / JXA                   →  .key slides & theming, .pages text & tables, formulas, sort, export, render checksMCP 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_servermcpb/               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 iWorkinstall.sh          one-line setup for the Claude desktop app

Contributing

git clone https://github.com/Arkanji/iwork-studio.git && cd iwork-studiouv run --extra test pytest -m "not aqua"      # headless suite, what CI runsuv run --extra test pytest -m aqua            # live suite: a Mac with Numbers, Keynote and Pagesscripts/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.