--- title: First session description: Start Atomic, run a first task, invoke a built-in workflow, and steer a run. --- # First session **Outcome:** You complete one interactive task and know how to monitor and steer it. **Prerequisites:** [Authentication](/getting-started/authentication) is complete. ## First session On a fresh install with no prior startup state, Atomic shows a one-time explanation of its coding-agent runtime and verifiable workflows. It appears after any What's New notes, directly above the input box. Returning users with prior startup state skip it automatically; stored credentials alone do not skip it. The normal Atomic input is ready from the start. Type a message, run `/login` if no provider is connected, or launch a workflow command. No separate onboarding step is required. The agent decides whether a workflow fits. Non-trivial work with structure and a verifiable objective runs as a workflow unless you ask for inline execution: implementation, bug fixes, debugging, migrations, multi-file changes with validation, and requests phrased as "repeat until" or "fix until green". Brainstorming, discussion, unclear goals, tiny low-risk answers or edits, or an explicit request to work inline, quickly or without a workflow stays inline. To launch, inspect the input contract with `workflow inputs`, then call `workflow run` with the registered workflow name and inputs. Ask only for genuinely missing information. Atomic can discover and run named builtin, project, user, and package workflows; author a rich custom TypeScript `workflow({...})` inline; and compositionally import reusable workflow definitions—including builtins from `@bastani/atomic/workflows/builtin`—into parent workflows with `ctx.workflow(...)`. Nested children can nest again within `maxDepth`, so custom graphs can combine proven research, implementation, design, verification, and approval workflows instead of copying them. They can also classify and branch, dynamically fan out and synthesize artifacts, run adversarial repair cycles, tournament-rank candidates, and loop until checks pass with explicit bounds. Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow. ## Verify the session Run one bounded task and watch it complete. In a repository you know, type: ```text List the top-level directories in this repository and say what each one holds. ``` Expected result: Atomic streams a response, calls `read` on a directory, `find`, or `bash` at least once — each tool call is shown inline as it runs — and finishes with a summary naming directories that actually exist in your checkout. A response that names nothing from your repository means the session started outside the directory you meant; quit, `cd` to the right place, and start Atomic again. Then confirm the session was recorded: ```bash atomic -r ``` Expected result: the session picker lists the run you just finished. That session is what `atomic -c` resumes. ## Go further With a session working, these are the fuller capabilities to reach for next. None of them is required for a first successful session. ### Try the built-in workflows Atomic ships with nine workflows you can run immediately. Use `/workflow list` to see them and `/workflow inputs ` to inspect their inputs in your environment. | Workflow | When to use | Example | |---|---|---| | `classify-and-act` | Route requests through structured classification and low-confidence human fallback. | `/workflow classify-and-act prompt="Triage and handle this request"` | | `fan-out-and-synthesize` | Partition independent slices, including repository-focused research, and synthesize their artifact evidence. | `/workflow fan-out-and-synthesize prompt="Map payment retries by subsystem and synthesize cited findings"` | | `adversarial-verification` | Challenge a candidate with fresh verifiers and bounded repair. | `/workflow adversarial-verification task="Verify the migration patch"` | | `generate-and-filter` | Generate, dedupe, filter, optionally judge, and shortlist candidates. | `/workflow generate-and-filter prompt="Propose names for the new command"` | | `tournament` | Compare whole solutions through balanced pairwise judging. | `/workflow tournament prompt="Design the retry strategy"` | | `loop-until-done` | Iterate with a durable ledger until completion or bound exhaustion. | `/workflow loop-until-done prompt="Repair failures until the test suite passes"` | | `goal` | Autonomous work that needs a durable ledger, bounded sub-agent orchestration, receipts, and reviewer-gated completion. | `/workflow goal objective="Update the CLI docs, add one example, and validate the docs build"` | | `ralph` | Research-first autonomous work with prompt refinement, delegated implementation, and iterative multi-model review. | `/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic"` | | `open-claude-design` | UI and design-system work with one generated preview, one live review session, and export. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |

Workflow List

Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `prompt="multi word value"` preserve useful types. If you call `/workflow ` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it. Goal and Ralph support `git_worktree_dir` only when you explicitly want a reusable worktree, and skip PR creation unless you set `create_pr=true` for the post-approval final stage. You can also launch workflows with **natural language** — describe the task in chat and ask Atomic to run a matching installed workflow or author a task-specific one: ```text Fan out repository research by subsystem, save cited findings as artifacts, and synthesize the evidence. ``` ```text Create a worker → fresh verifier → reducer workflow that updates the CLI docs, runs the docs build, and repairs evidence-backed findings until it passes or reaches a bounded stop. ``` ```text Use goal to update the CLI docs, include one example, run the docs build, and finish only when reviewers approve the evidence. ``` ```text Use ralph to research and implement specs/rate-limit.md, then review and repair it within three loops. ``` For natural-language launches, Atomic decides between inline work and a workflow as described above and preserves your explicit approval gates. Direct user `/workflow ` commands launch the named workflow. Goal provides a durable ledger and receipt-backed reviewer gate; Ralph provides a research-first implementation/review loop. Custom graphs can add domain-specific deterministic checks and bounded repairs. ### Monitor and steer a run Named workflow runs execute in the background. After launch you get the full run id; user-facing workflow surfaces show that complete UUID. You can still type the full id or a unique short prefix to inspect, connect, pause, quit, or resume a run. Ambiguous prefixes are reported rather than selecting a run arbitrarily. ```text /workflow status # inspect one run's progress /workflow status # list this session's active and terminal runs /workflow connect # see agents working; chat with or steer each stage (F2 also opens latest) /workflow attach # chat with one stage /workflow pause # pause resumably /workflow resume "go" # send a steer message and resume /workflow quit # pause gracefully and keep the run resumable ``` The below-editor `BACKGROUND` panel uses two lines per ordinary card at 80 columns and wider: the status glyph and full id are on the first line, and the workflow name plus mode/progress/elapsed metadata are on the second. A unique pending question adds a quoted one-line preview and `Answer: /workflow connect `. Below 80 columns it collapses to a count-only line. In chat surfaces, a full id wraps onto continuation lines at narrow widths instead of being cut, and the surrounding border remains intact. Human-in-the-loop prompts (`ctx.ui.input`, `confirm`, `select`, `editor`) surface in the graph viewer, not as chat modals — connect to the run to answer them. The BACKGROUND preview does not change that answering path. Atomic also posts main-chat lifecycle notices when a run completes, fails, or awaits input. If you answer a workflow prompt in the graph or attached stage chat, the main chat receives a display-only answer summary for audit; it does not wake the model, enter LLM context, or answer later prompts. See [Workflow Operations](/workflows/operations) for the full run-control reference. ### Top skills to invoke directly Skills are reusable expert instructions. Trigger one with `/skill:` followed by a request: | Skill | When to use | Example | |---|---|---| | `research-codebase` | Scoped research that writes a grounded artifact for one subsystem or question. | `/skill:research-codebase how the rate limiter works in src/middleware/` | | `create-spec` | Turn research into an implementation-ready plan. | `/skill:create-spec from research/docs/2026-03-rate-limit.md` | | `prompt-engineer` | Write, evaluate, migrate, or troubleshoot GPT and Claude prompts using separate model guides. | `/skill:prompt-engineer Draft a sharper repo-research prompt for payment retries end to end.` | | `tdd` | Test-first feature or bug work. | `/skill:tdd` | | `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks, framework-aware live review, and mount-failure recovery. | `/skill:impeccable` | | `agent-browser` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:agent-browser` | | `cua-driver` | Drive a native desktop app, simulator, or emulator window through Cua Driver: accessibility snapshot, element-token actions, and a fresh snapshot to verify. | `/skill:cua-driver` | | `qlty` | Lint, auto-format, and measure code quality — complexity, duplication, and code smells — through one CLI across the repository's languages. | `/skill:qlty check this branch before I hand it off` | | `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` | | `show-me` | Explain a topic visually with concise diagrams, code-shape sketches, or focused HTML artifacts. HumanLayer, MIT licensed. | `/skill:show-me` | Impeccable 4.7.0 runs its commands (`context`, `live`, `detect`, hooks, and the rest) through a self-contained engine binary instead of Node scripts. The bundled launcher, `scripts/impeccable` (`impeccable.cmd` on Windows), looks for a binary next to itself, then in `~/.impeccable/bin/`, and otherwise downloads the pinned engine release for your platform into `~/.impeccable/bin//` and verifies it against its published SHA-256 before running it, so the first use needs network access. Point `IMPECCABLE_BIN` at a preinstalled engine or set `IMPECCABLE_HOME` to a writable cache when that is not possible. Atomic's launcher keeps the engine's anonymous telemetry pings and its `npx impeccable update` check switched off, since the skill ships with each Atomic release. A concept roll still fetches its catalog with a `GET /api/roll` request to `impeccable.style`, which carries the scope, mode, a short seed key, and a re-roll counter, but no project files, prompts, code, or conversation. Live sessions resolve to the selected app root and support SvelteKit, Nuxt, TanStack Start, Astro, Next.js, Vite, and static HTML injection. The image fallback runs only with `OPENAI_API_KEY`, sends prompts and optional reference images to OpenAI, and spends that account's API credit. Generated image prompts are embedded in the image or a sidecar, so do not include secrets. Use `/skill:research-codebase` for a focused subsystem or question. For repository-wide research, use `fan-out-and-synthesize` with distinct repository partitions and an artifact synthesis barrier. Use Goal for ledger-backed bounded orchestration and Ralph for research-first delegated implementation with iterative review; task size alone does not select either workflow. ### Create your own workflow in natural language Named workflows may be builtin, project, user, or package supplied. You do not have to hand-write TypeScript to add a new workflow. Describe what you want in plain chat and Atomic will design and write it for you using [Builtins and Dynamic Workflows](/workflows/builtins) and the [Custom Workflow Authoring](/workflows/authoring) reference as its source of truth: ```text Create a reusable Atomic workflow called review-changes. It takes one required text input `target` (a diff, PR, or review focus). Run two reviewers in parallel with fresh context — one for correctness and missing tests, one for edge cases and maintainability — then a synthesis stage that consolidates findings into blockers vs. suggestions and returns { consolidated_review, decision }. ``` Atomic will: - ask clarifying questions if stage purpose, inputs, models, or handoffs are ambiguous, - write a `.atomic/workflows/.ts` definition that uses `workflow({ ... })` and imports `Type` from `typebox`, - run `/workflow reload` so the generated workflow is rediscovered and can be launched with `/workflow `, - then report the generated workflow folder so you can inspect the code it wrote, using `Custom workflow created. You can inspect its code at: ` (for example, `.atomic/workflows/`); Atomic does this only for newly created custom workflows, never builtin or pre-existing workflows. The same plain-chat approach works for editing or hardening an existing workflow. For the full authoring reference, see [Custom Workflow Authoring](/workflows/authoring), including composition with user-defined workflows and all nine builtins from `@bastani/atomic/workflows/builtin`. ### Default tools and prompts If you'd rather start with a plain prompt, just type a request and press Enter: ```text Summarize this repository and tell me how to run its checks. ``` By default, Atomic gives the model these tools: - `read` - read files - `bash` - run shell commands - `kill` - cancel owned background shell tasks by task ID - `edit` - patch files - `write` - create or overwrite files - `find` - discover files by glob pattern - `search` - search file contents - `ask_user_question` - ask structured questions in the TUI - `todo` - manage file-based todos On native Windows, `powershell` is also enabled when a PowerShell executable is available. Normal coding sessions include file discovery and content search through `find` and `search` in addition to `read`, `bash`, `edit`, and `write`. Atomic runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback. ## Next step Continue to [Project instructions](/getting-started/project-instructions).