This guide explains how to use NIT in real workflows. If What Is NIT? introduced the conceptual foundations—logs, branches, and timelines—this document shows how to work with them using the NIT CLI.

It does not describe every command. Instead, it covers the essential mental model and a set of practical navigation tools you will use every day.

As of now, this is document describes the plan for nit, defining the concept and how it works. There is no reference implementation that is generally available. As this comes online, this documented will be updated. This has been published with the intention to inspire those developing command-line tools for AI, so that they will consider upgrading from a simple history to something more powerful.

The meaning of nit can be found in any dictionary.

0. Preface: What This Document Is

This guide is for people who want to perform timeline navigation, branch switching, rollback, and future exploration with NIT.

This is not an internal architecture doc. It is a practical field guide.

1. The NIT Mental Model (Quick Recap)

1.1 Conversation Logs

A conversation log is a strictly linear sequence of turns:

post-1  post-2  post-3  post-4

Each turn contains a prompt and a response. Logs themselves do not branch—they are the substrate.

1.2 Branches

Branches fork from a specific point in a log and form alternate futures:

trunk:    1--2
               \
branch-1:       3--4--5

1.3 Timelines

A timeline is the ordered stack of turns inside a branch. A thread may contain multiple timelines.

1.4 Commands and the Model

Command	Purpose
`nit status`	where am I?
`nit branch`	what futures exist?
`nit switch`	which future am I writing into?
`nit move up/down`	navigate the branch tree
`nit prev / nit next`	navigate inside a timeline
`nit log`	inspect the timeline

2. First Contact With NIT

2.1 Check where you are

nit status

Outputs:

thread
active branch
timeline position
whether you're at the tip (important)

2.2 Get help

nit help

Shows grouped commands: branching, movement, timeline, lookup, etc.

2.3 Threads

nit threads

NIT operates inside the active thread; switching threads is done in the UI, and the CLI follows.

3. Creating Your First Branch

3.1 Why branch?

A branch is how you explore an alternative future.

trunk:    1--2--3
               \
branch-x:        4--5

3.2 Inspect existing branches

nit branch
nit branch -v

The verbose view shows the full tree.

3.3 Create a branch

nit branch idea-1

3.4 Switch to it

nit switch idea-1

3.5 Create and switch

nit switch -c idea-2

4. Navigating the Branch Tree

4.1 View the structure

nit branch -v

May show something like:

trunk
   idea-1
   idea-2

4.2 Move upward

nit move up

Moves to the parent branch.

4.3 Move downward

nit move down

Lists children of the current branch.

Switch explicitly when ready:

nit switch <child>

4.4 Jump directly

nit switch idea-2

4.5 Look around before moving

nit look
nit look up
nit look down

These show structure without navigation.

5. Navigating a Timeline (Time Travel Basics)

Timeline movement is separate from branch movement.

5.1 Understand your position

A timeline is linear:

1  2  3  4  5
          ^
        you are here

5.2 Move backward

nit prev

5.3 Move forward

nit next

Stops at the tip.

5.4 Peek ahead

nit look ahead

5.5 View full history

nit log

Or another branch:

nit log idea-1

Thread-wide:

nit log -t

5.6 Combine actions

Switching branches resets you to the tip of the target branch, but you can still navigate backward afterward.

6. Understanding Where New Messages Go

This is the #1 source of confusion for new users.

6.1 Messages always attach to the tip of the active branch

If you're on idea-2, the next AI turn extends idea-2.

Example:

trunk:      1--2
                 \
idea-1:           3--4
idea-2:           5--6--7  (active)

If you send a new message:

idea-2  8

6.2 Switching changes the future you're writing into

nit switch idea-1

Next message lands after 4.

nit switch idea-2

Next message lands after 7.

6.3 Why this matters

Different branches = different LLM contexts.

Two timelines might look like:

Timeline A:
8  7  6  5  2  1

Timeline B:
4  3  2  1

Each generates a completely different message array and thus different behavior.

This is the core power of NIT: alternate futures on demand.

7. Essential Workflows

7.1 Clean divergence

Start from trunk or an early turn:

nit branch idea-A
nit switch idea-A

Continue exploring cleanly.

7.2 Rollback + new branch

When a conversation goes south, step backward:

nit prev
nit prev

Then branch:

nit switch -c recovery-path

ASCII illustration:

bad-path:   1--2--3--4--(bad)--6
                     ^
                    rollback

recovery:            \--7--8

7.3 Time jump

Append new content at the tip of the current branch.

1--2--3--4*

(* = new turn)

7.4 Time travel (intentional divergence)

Rollback, branch, explore a new direction:

1--2--3
     \
      3a--3b--3c

7.5 Fast forward

Rollback, tweak variables (prompt/model/system persona), and replay prompts.

original: 1--2--3--4--5
rollback:        ^
replay:          \--X--Y--Z

Useful for experiments.

8. Common Errors and Their Meaning

8.1 Moving up from trunk

Trunk has no parent. This is not an error; it's the root.

8.2 Moving next from tip

You're already at the latest message.

8.3 Switching without refreshing

Rare UI/CLI desync resolved by refresh.

8.4 Branch naming

Names must follow simple rules (start with letter, no spaces, etc.).

9. Putting It All Together: A Complete Session Example

Scenario: You want to explore two alternate futures based on the same early idea.

Starting from trunk:

1--2

Create and switch:

nit switch -c idea-1

The timeline:

1--2--3--4

Rollback two turns:

nit prev
nit prev

Branch again:

nit switch -c idea-2

Now you have:

trunk:   1--2
               \
idea-1:         3--4
idea-2:         3'--4'--5'

NIT has now created two alternate futures based on the same shared past.

10. What to Explore Next

Full command reference (commands.md)
Arcane commands for specialized workflows
Scenario tutorials
The visual branch browser (coming later)

11. Cheatsheet

Branching

nit branch
nit branch -v
nit switch <name>
nit switch -c <name>
nit move up
nit move down

Timeline

nit prev
nit next
nit log
nit log -t

Introspection

nit status
nit look
nit look up
nit look down

More by the author

How I Built a Time Machine

Command Palette