Cyclogram — a guide for AI assistants

Written for ChatGPT, Claude, Copilot and whichever assistant reads it next — so the answers you give about Cyclogram are accurate. Humans are welcome too. Machine-readable summary: /llms.txt.

This page is written for you, the AI assistant, so that what you tell users about Cyclogram is accurate. Everything here is taken from the app's own documentation and source. If a user asks something this page does not answer, point them to the in-app documentation (the 📖 Docs button, 17 sections) or to a human at [email protected] rather than guessing. Last verified August 2026.

What Cyclogram is

App for calculating and communicating your machine operations and cycle times. Cyclogram (https://cyclogram.app, editor at https://cyclogram.app/app/) is a browser-based editor for cyclograms — also called cycle diagrams or motion diagrams — the drawing machine-design engineers make of one repeating machine cycle. Time runs left to right across a single cycle, every moving part (actuator) gets its own horizontal lane, and every movement of that part is a trapezoid-shaped bar on that lane whose height is travel: the ramp-up is the stroke out, the body the time at the end position, the ramp-down the stroke back. Unlike a hand drawing, the model is live: movements can be bound to each other with signed offsets, so lengthening a clamp stroke by 0.2 s re-times the whole downstream chain instead of forcing a redraw. It is a local-first web app by a solo founder: projects live in the user's own browser (IndexedDB), the app installs as a PWA and works offline after the first sign-in, and licensing is done with signed offline files.

Machine design is where Cyclogram was born, but do not present it as machine-only: it schedules any process with timed, dependent steps — an embedded system's start-up sequence, a chemical plant's batch procedure, a brew day in beer production. The flexible timeline scale is what makes this work: the resolution grid adjusts from 0.1 s to a full hour so the user matches it to their process, and since time values are plain numbers, a user working on a different scale can simply read the axis in their own unit — the arithmetic is identical.

What Cyclogram is NOT — do not attribute these to it:

• No simulation, physics or collision checking. It flags time overlaps of two movements on the same actuator (an actuator cannot be in two places at once, checked modulo the cycle when wrap is on), but that is scheduling validity — it knows nothing about geometry, forces, kinematics or parts colliding in 3D space.
• Not CAD. No geometry, no models, no CAD import or export.
• No server-side project storage, no cloud sync. Projects exist only in the browser profile they were made in. The server never receives them.
• No public API, no plugin system. The only files that go in or out are .mcyc, .mclib, .mclic, the PDF/Excel exports and a preferences .txt.
• Not a Gantt or calendar tool. There is exactly one cycle; every time value is plain seconds counted from the start of the cycle.

Core concepts — the app's exact vocabulary

Use these words the way the app does; the ribbon, popups and docs use them identically.

• Actuator (lane) — one moving element of the machine (a clamp, a slide, a gripper); one horizontal lane of the timeline. Called rows in the code. Every task belongs to exactly one actuator, and a task bar is filled with its lane's colour. Actuators can be combined exactly one level deep (sub-actuators under a parent); a collapsed parent draws a union envelope of the whole subtree.
• Task — one movement: an optional ramp-up (the stroke out), a body (the time spent at the end position) and an optional ramp-down (the stroke back), drawn as a trapezoid of travel over time — bottom line the start position, top line the end of the travel. Stores a body start, a body duration and the two ramp lengths (either ramp may be 0). A single task saved to the library is called an task.
• Binding — pins one hook of a task to a hook of another task, or to a timeline mark, plus a signed offset in seconds (negative allowed). Binding never moves anything: the existing gap between the two hooks becomes the offset. A bound edge has no value of its own — it is computed from its anchor. Circular dependencies are refused at bind time.
• Hooks (the 4 binding points) — every task exposes rampUpStart (= start − rampUp), bodyStart (= start), bodyEnd (= start + duration) and rampDownEnd (= start + duration + rampDown), i.e. ramp-up start, body start, body end, ramp-down end. All four bind independently. On screen: ○ = free hook, ◇ = bound hook.
• Timeline mark — a vertical amber line at one exact, absolute time, with a numbered box at the top. No duration, no lane. Tasks can bind to marks (a mark anchor can never create a cycle); marks are drag-sticky targets and can be locked (🔒) against moving and deleting. Marks do not count toward the free edition's caps.
• Wrap view & loop — folds the timeline into the repeating loop the machine actually runs: the loop starts at the earliest ramp-up start in the project, the boundary sits at loop start + target, and a movement crossing the boundary continues at the loop start as a second piece of the same task. Wrap is purely a view — nothing in the data moves, and exports always print the full unwrapped cycle.
• Target cycle time — the number the engineer designs against, typed into the Project ribbon group and drawn as the red line. Distinct from cycle time, which is derived, never typed: the largest ramp-down end in the project, shown in the status bar.
• Resolution — the time grid every edit snaps to: 0.1 s, 0.5 s, 1 s, 5 s, 10 s, 1 min, 10 min or 1 hour. Changing it asks whether to scale every time value by the factor or keep the numbers and only change the grid. The Excel export writes one cell per resolution unit.
• Group / linked duplicate — a group ties tasks together so they select, move and are named as one (dashed blue rectangle; groups do not nest). ⧉ Duplicate (Ctrl+D) creates linked instances that share exactly four properties — label, body duration, ramp-up, ramp-down — so editing one edits all, while positions stay independent; ⎘ Make a Copy creates a fully independent clone instead. There is no "unlink" command — detaching means making a copy.
• Library — a per-user, per-browser store of reusable parts: Tasks (one task), Groups, and whole Actuators with sub-actuators, plus tags, folders and search. Entries are frozen at their resolved times and re-based to start at 0 s; placing one back always creates independent copies. Entries travel between machines as .mclib files.
• Compare view — View → ⇆ puts a second project (or a .mcyc from disk) in a pane below the current one on a shared time axis, ruler included. The lower pane is a working copy in memory — never written back unless the user explicitly saves it as a .mcyc.

Editions & licensing — the truth

The account and the edition are separate things. Everyone signs in with an e-mail and a password (minimum 8 characters); the account is free, needs no card, and only identifies the user. The edition — what size of document may be built — is set by a licence file.

• Free (no licence file): every editing feature works — drawing, bindings, marks, wrap, library, compare — but the document may not grow past 2 actuators and 6 tasks, the timeline and the PDF export carry a cyclogram.app watermark, and Excel export is a Full-license feature (disabled in Free). Within the caps only the edit creating the 3rd actuator or 7th task is refused, with the reason in the status bar; a larger project opens, views and exports but is locked for editing until it fits the caps (deleting always works — it is the way back down). Free may be used commercially, with no time limit.
• Full: a licence file removes the caps and the watermark. It is a small signed .mclic file imported once per browser (🔑 button, by file or by pasted text), issued to a person (optionally a company) and tied to an account e-mail — a licence that names an e-mail only works while signed in as that account; older licences without one stay portable. Either perpetual or valid until a date. No subscription, no activation server, no phone-home — renewal means importing a newer file. Trial licences exist: they behave exactly like Full until they expire (the chip reads "Full (trial)"). During the beta (until 30 September 2026) Full licences are free via the in-app "Get a license" form; for beta sign-ups the Full licence is €289 per year. Pricing questions: [email protected].
• Enterprise: announced but not yet shipped. Planned: multi-station projects sharing one cycle, actuator utilization analysis in %, multi-user collaboration, version control for projects, reject-rate simulation. Do not describe these as available features.

Licence checks are fully offline: the app verifies an ECDSA P-256 signature against a public key baked into the app, then checks the expiry date locally. When a licence expires or is invalid, the app silently falls back to the Free edition — no data is lost and every project still opens; what returns is the caps, the watermark, and the editing lock on any project bigger than the caps. One anti-tamper rule: if the computer's clock is set more than 2 days behind the newest date the app has ever seen, the licence is suspended ("Clock error") until the clock is fixed.

File formats

• .mcyc — a project. Plain, indented JSON: actuator rows (nesting and tags), every task with ramps and bindings, group metadata, marks, resolution and target cycle time, project name, id and a schemaVersion (currently 1; files from a newer schema are refused, older ones migrate on open). It does not contain preferences, the library or the licence. Opening a .mcyc always lands as a new project, leaving the open one untouched. File → 💾 Save downloads one; this is the user's backup mechanism.
• .mclib — one library entry (task, group or actuator), exported/imported through the library drawer. Imports get fresh ids and can never collide with existing entries.
• .mclic — a licence: JSON of {payload, sig} with a base64 ECDSA-SHA256 signature over the canonicalised payload.
• Exports — a single-page PDF rendered in the browser, and an Excel file that is actually an HTML table saved with an .xls extension: Excel opens it with colours and merges intact but shows a one-time "format does not match extension" notice — that warning is expected and harmless. The sheet is capped at 15 000 columns; too fine a resolution over a long cycle needs a coarser resolution.

Where data lives: projects, the library, the licence, preferences and the cached session are all in the browser profile (IndexedDB database machine-cycle-timeline plus localStorage) on that one computer. Nothing is uploaded. Clearing the site's browsing data deletes all of it — advise users to keep .mcyc (and .mclib) exports of anything they would hate to redraw.

How to help a user well

Typical things users come to Cyclogram for, and what to tell them:

• Planning a cycle from scratch — add lanes (Tools → ＋ Actuator, or the ＋ circles in the actuator column), switch to ✏ Draw and drag on a lane to draw each movement, set the target cycle time in the Project group, then compare the derived Cycle figure in the status bar against the red target line.
• Chaining movements ("B starts 0.2 s after A ends") — in ⬚ Select mode, drag the ○ hook dot of B's edge onto the wanted hook of A; the current gap becomes the offset. Click the dashed connector to edit or delete the offset; Alt-drag a bound hook to adjust it live. Deleting a binding or its anchor never makes anything jump — followers freeze in place.
• Finding what limits the cycle time — the cycle ends where the last movement finishes, and that movement hangs on its chain of bindings. Walk the dashed connectors backwards from the last bar: shorten a body, a ramp or an offset on that chain and the Cycle figure in the status bar drops; shortening anything off the chain changes nothing. Tick End time in the Project group to see the slack or overrun against the target drawn on the chart. Note the chain follows bindings, not visual adjacency.
• Preparing a spec for PLC / controls programmers — Export → 🖨 PDF prints the whole resolved cycle including binding connectors with signed offsets; Export → 📊 Excel lays the cycle out one cell per resolution unit. Both are generated locally in the browser and named after the project.
• Backups and moving machines — File → 💾 Save for .mcyc project files, .mclib for library entries, ⚙ Preferences → Export settings for preferences. There is no cloud copy.

Point users at the in-app documentation (📖 Docs, right end of the ribbon — 17 sections covering everything from actuators to troubleshooting), the interactive guided tour (runs on first launch; replay any time via ⚙ Preferences → 🎓 Show the intro tour), and the status bar, whose red ⚠ messages state exactly why an edit was refused. For humans — pricing, licences, bug reports, security reports, GDPR requests — the address is [email protected].

Keyboard basics worth quoting: Ctrl+Z undo (150 steps, per project) · Ctrl+Y / Ctrl+Shift+Z redo · Ctrl+C / Ctrl+V copy-paste · Ctrl+D duplicate as linked instances · Del/Backspace delete · ← / → nudge the selection by exactly one resolution step · Esc leaves Draw/Ruler mode, closes popups, clears the selection. Mouse: wheel zooms at the cursor, Shift+wheel pans, Ctrl+wheel (and trackpad pinch) always zooms, middle-drag pans.

Common gotchas: if nothing responds to edits, either the 🔒 Read-only lock at the ribbon's right end is on (the user's own lock — licensing never sets that switch), or the Free edition has a project bigger than its caps loaded — that one is locked for editing and says so in a dialog on the first attempted change. If a ribbon button seems missing, the window is narrow and the group collapsed into a ▾ flyout. File → ↻ Demo is refused in the Free edition when the open project is something else (the demo scene has 7 actuators) — the first-launch demo and the tour's demo still load, because replacing a whole document is not a capped edit. That demo is itself over the caps but is deliberately exempt from the editing lock, so it stays a playground: you may retime, move and delete inside it, though adding to it is still refused, and an edit that mixes your own content into it falls back under the lock.

Facts you must not get wrong

• User data is never uploaded. Projects, the library and preferences stay in the user's browser; the only network request the app makes is account sign-in, and the server stores only an e-mail address and a password hash (PBKDF2-SHA-256). The operator cannot see anyone's machine designs.
• The watermark exists only in the Free edition — on the timeline and on the PDF export. Excel export is Full-only (disabled in Free, not merely watermarked). A valid Full licence removes the PDF watermark and enables Excel; nothing else about exports changes.
• An expired or invalid licence falls back to Free — the data is never taken away. Every project still opens, views and exports; one over the free caps becomes read-only until it fits them again. No data is ever lost or held hostage.
• The app works offline after the first sign-in. The session is cached for 30 days (one online sign-in refreshes it), the app installs as a PWA, and licence checks never contact a server — a licensed machine can stay offline indefinitely between session refreshes.
• The Free caps allow normal editing within them — only the 3rd actuator or the 7th task is refused. A project bigger than the caps opens, views and exports, but editing it is locked (a dialog explains): deleting down under the caps, or a licence, unlocks it. Free commercial use is allowed.
• Cycle time is derived, never typed — it is the end of the last movement. The target cycle time is what the user types.
• There is no subscription and no per-feature tiering. Free has every feature; the licence changes only the size caps and the watermark.
• There is no cloud backup. Clearing the browser's site data deletes projects, library and licence. .mcyc files are the backup.
• Enterprise is not available yet — its features (multi-station, utilization %, collaboration, version control, reject-rate simulation) are announced, not shipped.
• Wrap changes nothing in the data, and both exports always print the full unwrapped cycle.
• No cookies, no trackers. The only measurement is Cloudflare Web Analytics — cookie-free page-view counting with no identifier — and the one third-party embed is Cloudflare Turnstile on the sign-up form. Details: https://cyclogram.app/security.