{"id":49441306,"url":"https://github.com/lkuczborski/codeck","last_synced_at":"2026-05-08T19:01:06.756Z","repository":{"id":354244028,"uuid":"1222699510","full_name":"lkuczborski/Codeck","owner":"lkuczborski","description":"Native macOS Markdown presentation maker for teaching and running live Codex prompting workflows.","archived":false,"fork":false,"pushed_at":"2026-05-01T20:00:38.000Z","size":5185,"stargazers_count":32,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T23:03:58.570Z","etag":null,"topics":["codex","codex-cli","markdown","presentation-slides"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lkuczborski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T16:10:18.000Z","updated_at":"2026-05-02T12:51:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"6dc5a088-a7bc-4be0-b114-5e255b8f0517","html_url":"https://github.com/lkuczborski/Codeck","commit_stats":null,"previous_names":["lkuczborski/codeck"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lkuczborski/Codeck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkuczborski%2FCodeck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkuczborski%2FCodeck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkuczborski%2FCodeck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkuczborski%2FCodeck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lkuczborski","download_url":"https://codeload.github.com/lkuczborski/Codeck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lkuczborski%2FCodeck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32589264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex","codex-cli","markdown","presentation-slides"],"created_at":"2026-04-29T20:02:10.283Z","updated_at":"2026-05-08T19:01:06.749Z","avatar_url":"https://github.com/lkuczborski.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codeck\n\n![Codeck screenshot](screenshot.png)\n\nCodeck is a native macOS document-based Markdown presentation maker for teaching Codex prompting workflows.\n\n## Examples\n\nThe [`Examples`](Examples) folder contains sample `.mdeck` decks:\n\n- [`CodeckFeatureCarnival.mdeck`](Examples/CodeckFeatureCarnival.mdeck) is a\n  short, playful tour of Codeck's core workflow: Markdown slides, themes, live\n  preview, presentation mode, web images and GIFs, and runnable Codex cards.\n- [`SyntaxHighlighting.mdeck`](Examples/SyntaxHighlighting.mdeck) shows fenced\n  code highlighting across the supported language labels and aliases.\n\n## Document format\n\nDocuments use the `.mdeck` extension so macOS can associate them with Codeck\ninstead of the system Markdown editor. The body remains Markdown. Slides are\nseparated by a line containing only:\n\n```markdown\n---\n```\n\nDeck-level settings live in YAML front matter:\n\n```markdown\n---\nformat: codeck.mdeck\nversion: 1\ntheme: studio\ncodex:\n  sandbox: read-only\n  model: \"gpt-5.5\"\n  reasoning: medium\n---\n\n# First Slide\n```\n\nSupported deck metadata:\n\n- `format`: should be `codeck.mdeck`.\n- `version`: current document version is `1`.\n- `theme`: presentation theme. Supported values are `studio`, `midnight`,\n  `chalk`, `solar`, and `atelier`.\n- `codex.sandbox`: default sandbox for live Codex sessions. Defaults to\n  `read-only`.\n- `codex.model`: default model for live Codex sessions. Codeck fetches the\n  available model list from `codex app-server` and falls back to `gpt-5.5` if\n  Codex is unavailable.\n- `codex.reasoning` or `codex.reasoning_effort`: default reasoning effort.\n  Codeck fetches the supported values for the selected model from Codex and\n  falls back to `low`, `medium`, `high`, and `xhigh`. Defaults to `medium`.\n\n## Live Codex sessions\n\nAdd a fenced `codex` block to a slide:\n\n````markdown\n```codex id=refactor-demo\ntitle: Explain the refactor goal\nmodel: gpt-5.5\nreasoning: xhigh\nsandbox: read-only\n\nExplain how to refactor this SwiftUI view into smaller subviews.\n```\n````\n\nDeck defaults for model, reasoning, and sandbox are applied to every Codex\nblock. Any block can override those values with its own metadata.\nLive sessions run through `codex app-server --listen stdio://`, so Codeck needs\nthe Codex CLI available on `PATH` and an active Codex login.\n\nSupported block metadata:\n\n- `id`: stable session id used for output tracking and slide buttons. It can be\n  written on the opening fence, as shown above, or as a metadata line.\n- `title`: display title for the live Codex card. This should describe what the\n  prompt is meant to demonstrate.\n- `model`: per-block model override.\n- `reasoning` or `reasoning_effort`: per-block reasoning override. Supported\n  values come from the selected Codex model.\n- `sandbox`: per-block sandbox override. Common values are `read-only`,\n  `workspace-write`, and `danger-full-access`.\n\nCodeck always shows the Markdown response from Codex. While a session is running\nand before the first response token arrives, the output area shows `Thinking...`.\n\nThe prompt starts after the first blank line following the metadata.\n\nEach live Codex card has its own run button on the slide. When a slide contains\nmultiple Codex sessions, a slide-level run-all button appears in the top-right\ncorner. Codex responses stream into the slide live and are rendered as Markdown,\nso lists, headings, tables, code, links, and images in the response use the same\nrenderer as the rest of the deck.\n\nFenced code blocks support syntax highlighting when the opening fence includes a\nlanguage, such as ```` ```swift ```` or ```` ```json ````.\n\n## MCP server\n\nCodeck includes a file-based MCP server so other agents can create and edit\n`.mdeck` decks without driving the macOS UI. Build or run the `codeck-mcp`\nexecutable from the repository root:\n\n```bash\nswift run codeck-mcp\n```\n\nBy default, the server can read and write only inside its current working\ndirectory. Set `CODECK_MCP_ALLOWED_ROOTS` to a colon-separated list when an MCP\nclient should work elsewhere:\n\n```bash\nCODECK_MCP_ALLOWED_ROOTS=\"$HOME/Documents:/tmp\" swift run codeck-mcp\n```\n\nThe server speaks MCP over stdio and exposes tools for deck and slide mutation:\n\n- `create_deck`\n- `read_deck`\n- `list_slides`\n- `get_slide`\n- `set_slide_markdown`\n- `insert_slide`\n- `delete_slide`\n- `move_slide`\n- `duplicate_slide`\n- `set_deck_settings`\n- `insert_codex_block`\n- `validate_deck`\n\nIt also exposes a resource template for read-only deck context:\n\n```text\ncodeck://file/deck{?path,view,index}\n```\n\nUse `view=document` for the full Markdown document, `view=outline` for a JSON\noutline, or `view=slide\u0026index=0` for a specific slide. Slide indexes are\nzero-based; slide UUIDs are runtime-only and are not persisted in `.mdeck`\nfiles.\n\n## Live MCP bridge\n\nCodeck can also expose the currently open app windows through a localhost MCP\nbridge. This is disabled by default.\n\nTo enable it in the app:\n\n1. Open Codeck settings.\n2. Enable **MCP \u003e Live Bridge**.\n3. Keep Codeck running with the deck window open.\n\nWhen enabled, Codeck listens on:\n\n```text\nhttp://127.0.0.1:49747/mcp\n```\n\nThe live bridge uses MCP Streamable HTTP with JSON responses. Configure an\nagent or MCP client with a Streamable HTTP server named `codeck` pointing\nto that URL. For clients that use the common JSON MCP manifest shape, the entry\nlooks like:\n\n```json\n{\n  \"mcpServers\": {\n    \"codeck\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"http://127.0.0.1:49747/mcp\"\n    }\n  }\n}\n```\n\nSome clients use `type: \"http\"` or `type: \"streamable-http\"` instead of\n`transport`; use the field name expected by that agent, but keep the same URL.\nAfter adding the server to the agent, ask it to call `list_open_decks` first so\nit can get the live `document_id` for the Codeck window it should edit.\n\nLive bridge tools:\n\n- `list_open_decks`\n- `read_deck`\n- `list_slides`\n- `get_slide`\n- `set_slide_markdown`\n- `insert_slide`\n- `delete_slide`\n- `move_slide`\n- `duplicate_slide`\n- `set_deck_settings`\n- `insert_codex_block`\n- `select_slide`\n- `get_selection`\n- `start_presentation`\n- `stop_presentation`\n- `validate_deck`\n\nLive bridge resources use:\n\n```text\ncodeck://live/deck/{document_id}{?view,index}\n```\n\nUse `view=document` for full Markdown, `view=outline` for a JSON outline, or\n`view=slide\u0026index=0` for a specific slide. The shared `codeck://` scheme uses\n`file` and `live` host segments so agents can distinguish file-backed deck\nresources from open app-window resources.\n\n## Presenting\n\nPress the toolbar play button to start a full-screen presentation from the\nselected slide. Use the left and right arrow keys to navigate and Escape to exit.\n\n## Local run loop\n\nUse the project run script:\n\n```bash\n./script/build_and_run.sh\n```\n\nThe Codex app Run button is wired to the same script through `.codex/environments/environment.toml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkuczborski%2Fcodeck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flkuczborski%2Fcodeck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkuczborski%2Fcodeck/lists"}