# Working with projects

Create projects from scratch or from a GitHub repo, organize them, and browse their files.

Canonical page: https://app.teachervoiceai.com/docs/guides/working-with-projects

A **project** is one git repository plus its Machine configuration. It's the
container for everything — sessions, secrets, connected tools, deployments, and
members. This guide covers creating and managing them from the dashboard.

## Create a project

### Start fresh or import

From your projects list, choose **New project**, then pick how it starts:

- **Start fresh** — Machine creates and manages a new git repository for you.
Good when you're building something new and don't already have a repo.
- **Import a repository** — connect GitHub and select an existing repo. Machine
works against your repository directly; sessions branch from it and land work
through review.

### Connect GitHub (for imports)

If you're importing, you'll connect the GitHub App to the org or account that
owns the repo, then pick the repository. Machine only gets access to the repos
you grant, and uses short-lived, per-session credentials when an agent works.

### Open the project

The **project home** is your launch pad: the session composer to start work, plus
tiles for the project's features — sessions, changes, connected tools, secrets,
deployments, and more.

## Organize your projects

From the projects list you can:

- **Search** by name, repository URL, or branch to find a project fast.
- **Rename** a project to keep things tidy.
- **Archive** a project you're done with — it's hidden from the main list without
  deleting the underlying repository.
- **Switch accounts**, or use the **all accounts** view to see every project you
  can access across the accounts you belong to.

## Browse project files

Open a project's **Files** to browse its repository — navigate the tree, view a
file's contents, search by filename or content, and look at a file's commit
history. It's a read-oriented view of the repo as it stands on the default
branch; agents make changes on their own branches inside
[sessions](/docs/guides/running-a-session).

> **Info**
> A project works best when it's **focused** — one product, service, or idea per
> project. Smaller, well-scoped repos give agents tighter context and faster
> sandboxes than one giant monorepo.

---

**Next:** [Running a session](/docs/guides/running-a-session) · [Customizing your project](/docs/guides/customizing-your-project) · [Projects concept](/docs/concepts/projects).