# Starting a project

> Makes a new project that compiles — blank, or from a starter — with the instructions your coding agent works from and, for Claude, settings that keep the agent inside the project. Then it tells you the one next step: open your agent and describe the app.

<!-- id: local-starting-a-project · area: local · stability: stable · html: https://osysharp.com/reference/local/starting-a-project/ -->

## Summary        {#summary}

`osy init` turns a folder into an Osy# project: a small app that compiles and has a passing test, the instructions
your coding agent reads, and the editor setup. When it is done it says only what to do next — open your agent in the
folder and describe the app you want, then `osy launch` to see it.

**There are two ways to start, and only two:** a **blank** project (`osy init`) and a **starter**
(`osy init --starter <name>` — a shell to fill in). A blank project needs no network at all; a starter fetches the
published kits it uses as it is laid out (see below). A word in the first
place — `osy init kanban`, `osy init my-app` — is refused with both ways and with `--name`, which is how the app is
named. The sample apps are for **reading**: `osy docs sample` lists them and prints one.

## Signature      {#signature}

```console
osy init --agent <claude|agent> [--starter <name>] [--title <Title>] [--size <try|core|whole>] [--name <Name>] [--directory <dir>] [--force]
```

## Description    {#description}

**What it writes.**

- `app.osy`, a page, a theme and a test — the minimum app, anonymous, so it runs before you have written anything.
  `osy init` asks nothing first: this is what you get unless you name a starter.
- **`--agent claude`**: `CLAUDE.md` (how to write Osy# and use this toolchain), the design skill, and
  **`.claude/settings.local.json`**: validate after every edit, and the rules that **keep the agent inside this
  project** (below). It is added to the project's `.gitignore`.
- **`--agent agent`**: `AGENTS.md`, the same instructions, for any other agent.
- `osyrin.json` and `.vscode/`, so F5 launches the page you are on.
- A `.gitignore` that keeps **`.secrets`** out of version control, whichever agent you chose — the file where
  [`osy secret set`](https://osysharp.com/reference/local/giving-a-secret-its-value/) keeps a credential's value in plain text — so the project is
  safe to commit from its first minute. An existing `.gitignore` is appended to, never replaced.

A file that already exists is left as it is and listed as skipped; `--force` writes it again. The one exception is
`.claude/settings.local.json`, which is merged rather than written: anything already in it — permissions you granted
Claude, your own rules — is kept, and the hook and the rules are added once.

**`--dry-run` writes nothing** and lists what a real run would write or change, with `--json` as one object
(`{"dryRun": true, "written": [...], "kept": [...]}`, paths relative to the project). It is how a tool asks before it
lays the agent's files into a project somebody brought: Studio's **Add a folder** shows that list for a project with
no `CLAUDE.md` and writes it only if you say so — or adds the project with nothing but its own `.studio` folder.

**Starting from a shell — `--starter`.** A starter is the structure an agent would otherwise spend its first minutes
making, and nothing more: the kits for signing in wired, the roles, a frame with the navigation, one
**empty** page per area with its address and who may open it, a test and a picture for each, one set of sample data
with an account for each role, and a placeholder look. No feature is built; every place to fill in is marked
`FILL IN`, and the project's `NOTES.md` says what is where. It is not a sample — a sample (`osy docs sample`) is a
finished small app to read.

| starter | the shape |
|---|---|
| `members` | people sign in, and what each may do depends on their role |
| `booking` | a public page that says what can be booked, pages for the person booking, one for the staff |
| `shop` | what is for sale, a basket, a customer's own orders, the staff side |
| `site` | a public site with one area where an admin changes it |
| `agents` | an AI agent does part of the work and people stay in charge of it: sign-in, one agent with one typed skill, a scripted model, the screens an admin runs agents from |
| `blank` | the minimum project — what `osy init` makes when no starter is named |

`--title "Book club"` is the app's name as people read it on screen (default: the app's name).

**A starter is ready as it is laid out.** Its sign-in kits are published packages, so `osy init --starter` resolves
them there and then — the same thing `osy lock` does — and writes the project's `osyrin.lock`: the kits your `osy`
carries (`Osysharp.Ui` and the platform's own) come from the binary, the rest are fetched from their public releases,
with no account and no token. `osy validate`, `osy test` and `osy launch` then work with no step in between. If the
computer cannot reach github.com, the project is still laid out and the screen says so: run `osy lock` in it once
you are online. A starter carries no lock of its own, so it can never name a version of a kit other than the one
your `osy` has.

**The look of a starter is left alone.** Its theme and shell are a plain placeholder — readable, good enough for a
first version — and its notes tell the agent to fill in the marked places and leave the look as it is, unless you
asked for a look or gave pictures to follow; then the look is a part of its own, the last one.

**How big a build the agent is told to make — `--size`.** The instructions file says how to work as well as how to
write Osy#, and how much thinking a build deserves depends on what you are after. `--size` chooses:

| size | what the agent is told | what you give up |
|---|---|---|
| `try` | One screen that works, shown within minutes: plain app code, the kit's own look, a kit only for signing in, no analysis first. What it left out is listed in `NOTES.md`. | It is a sketch: a plain look, nothing reusable, few tests. |
| `core` | The main journeys working end to end, one visible part at a time: one pass over the kits, existing kits where they clearly fit, no new kits written, one look decided in a sentence. | The wider application a complete product would have, and kits of your own. |
| `whole` | The whole application, thought through first: every capability mapped, every fitting kit inspected, new reusable kits written and tested, a designed look. **The default.** | Time: the first screen comes after the analysis. |

The language, the toolchain and the project layout are taught the same way at every size; only how much to analyse,
search and design before the first page differs. The size changes the instructions file and nothing else — the
project that is laid out is the same.

**Staying inside the project.** An agent that searches your whole computer for an answer is reading things that are
none of its business. The instructions say to work only inside the project, because everything else it needs — the
language, the kits, their source — the CLI answers. `.claude/settings.local.json` makes that hold for Claude's file tools:
it denies reading and editing everything in your home directory except

- this project,
- the toolchain's own folder, `~/.osy` — where a local platform's logs are — **but not** its package cache
  (`~/.osy/packages`), which holds every kit's source unpacked; the agent reads a kit through `osy kit` instead,
- where the CLI is installed, and
- Claude Code's own folder for this project, where it keeps a long command result for the agent to read back.

A permission rule names paths; it cannot say "everything but". So the file lists your home directory's entries one by
one, and on the way down to the project it lists the project's neighbours. The paths are this machine's, which is why
they go in Claude Code's per-machine file and not in `.claude/settings.json`, which a team shares: after moving the
project, run `osy init --agent claude` again — it adds the new rules and drops any old one that would keep the agent out
of the project's new folder. Folders outside your home directory are not listed — they hold the system, not your things.

**What it says when it finishes.** The next step, and nothing else:

```text
✓ Project ready.
Next: open Claude in this folder (claude) and describe the app you want — who uses it and what they do.
Then osy launch opens it in your browser.
```

## Examples       {#examples}

```console
mkdir bakery && cd bakery
osy init --agent claude          # the minimum app, CLAUDE.md, and the settings that keep Claude in this folder
```

```console
osy init --agent claude --size try    # the same project; the agent is told to make one working screen, fast
```

```console
osy init --agent claude --dry-run --json   # writes nothing: {"dryRun":true,"written":["CLAUDE.md", ...],"kept":[...]}
```

```console
osy init --agent claude --starter members --title "Book club"   # sign-in, roles, a frame and empty pages, ready to fill in
```

```console
osy init --agent agent --name Bakery    # the blank project, named, with AGENTS.md for another agent
```

```console
osy docs sample kanban                   # READ a finished small app — not a way to start one
osy docs sample kanban --into ../kanban  # …or take a copy of it to run and take apart
```

## See also       {#see-also}

- [Launching your app](https://osysharp.com/reference/local/launching-your-app/) — `osy launch`, the step after describing the app.
- [The inner loop](https://osysharp.com/reference/local/the-inner-loop/) — compile, test, look; what the agent does for you.
- [Finding a kit, and learning one from its tests](https://osysharp.com/reference/local/finding-a-kit/) — `osy kits find`, how the agent finds a kit without searching your computer.