Atlas

Atlas is a command-line tool for exploring and understanding software projects.

Atlas analyzes a codebase and builds a map of its structure and composition, giving developers a quick overview of what a project contains and how it is organized.

What is Atlas?

Large codebases can become difficult to understand.

Before changing a project, developers often need to answer simple questions:

How large is this project?
What languages does it use?
How many files does it contain?
Where is the code located?
What parts of the project are the largest?
How are its components related?

Atlas is designed to answer these questions from the command line.

Give Atlas a project directory:

atlas .

And it builds a high-level map of the codebase.

Example

ATLAS 🗺️
────────────────────
Project      atlas
Root         /home/ttomer/projects/atlas
Files        8
Directories  0
Size         20.94 KB
Lines        1 068

Languages
  V      5 files (62.50%)
  Other  3 files (37.50%)

The goal is simple:

Understand the project before diving into the code.

Why Atlas?

Modern development environments provide powerful tools for working with individual files and symbols.

Atlas approaches the problem from a different direction.

Instead of asking:

"What does this function do?"

Atlas starts with:

"What is this project made of, and how is it put together?"

Atlas is not intended to replace:

IDEs
Linters
Formatters
Static analysis platforms
Code review tools
Version control systems

It is a lightweight codebase exploration and intelligence tool.

Features

Current

Atlas v0.2 currently provides:

Project discovery
File scanning
Directory scanning
File count
Directory count
Project size
Physical line count
Programming language detection
Language statistics
Human-readable terminal output
JSON output
Project tree with configurable depth (atlas tree --depth N)
File type distribution
Top-level directory summaries
Optional extension statistics (--extensions)

Coming later

Atlas will progressively understand more about the codebase:

Project structure visualization
Import and dependency analysis
Symbol detection
Functions and classes
Internal relationships
Dependency graphs
Circular dependency detection
Codebase hotspots
Route detection
Machine-readable project information
File explanations

The long-term goal is to move from simply scanning a project to actually mapping it.

Installation

Atlas is currently in early development.

Requirements

You will need:

V
Git

Check your V installation:

v version

Clone the repository

git clone https://github.com/ChrizzzDev/atlas.git
cd atlas

Build Atlas

v .

This produces the Atlas executable in the project directory.

You can then run:

./atlas .

Development mode

Alternatively, run Atlas directly through V:

v run .

Usage

Atlas works directly from the command line.

Analyze the current directory

atlas .

Analyze another project

atlas /path/to/project

For example:

atlas ~/projects/seyfert

Atlas will scan the target project and display a summary of its composition.

Output

Atlas separates its analysis into several pieces of information.

Project information

Project      seyfert
Root         /home/ttomer/projects/seyfert
Files        416
Directories  49
Size         2.59 MB
Lines        74 144

Languages

Languages
  TypeScript  311 files (74.76%)
  Other       103 files (24.76%)
  JavaScript  2 files (0.48%)

As Atlas evolves, these sections will become increasingly detailed.

Supported languages

Atlas currently recognizes the following extensions:

Language	Extensions
V	`.v`
TypeScript	`.ts`, `.tsx`
JavaScript	`.js`, `.jsx`
Go	`.go`
Rust	`.rs`
Java	`.java`
C#	`.cs`
C++	`.cpp`
C	`.c`
Python	`.py`
PHP	`.php`
Kotlin	`.kt`
Swift	`.swift`

You can check out all the supported languages in by clicking here

Roadmap

Atlas is being developed incrementally.

The project intentionally starts with simple and deterministic analysis before introducing deeper code intelligence.

      ATLAS
        │
        ▼
┌───────────────┐
│     v0.1      │
│    Explorer   │ 
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     v0.2      │
│   Structure   │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     v0.3      │
│  Dependencies │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     v0.4      │
│    Symbols    │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     v0.5+     │
│ Relationships │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│     v1.0      │
│     Atlas     │
└───────────────┘

v0.1 • Explorer

v0.2 • Structure

v0.3 • Dependencies

v0.4 • Symbols

v0.5+ • Relationships

v1.0 • Codebase Intelligence

The first stable release aims to provide a complete high-level representation of a software project.

Potential commands:

atlas .
atlas tree
atlas stats
atlas deps
atlas symbols
atlas graph
atlas hotspots
atlas cycles
atlas routes
atlas explain

Architecture

Atlas is designed around a pipeline where each stage adds another layer of understanding.

┌──────────────┐
│  Filesystem  │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Scanner    │
└──────┬───────┘
       │
       ▼
┌───────────────┐
│ Project Model │
└──────┬────────┘
       │
       ▼
┌──────────────┐
│   Analyzers  │
├──────────────┤
│ Files        │
│ Dependencies │
│ Symbols      │
│ Graph        │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    Output    │
└──────────────┘

This architecture allows Atlas to become more sophisticated without turning the core scanner into a large monolithic system.

Project Structure

The current project is intentionally small:

atlas/
├── main.v
├── output.v
├── project.v
├── scanner.v
├── languages.v
├── v.mod
├── README.md
└── ...

Each component has a focused responsibility.

File	Responsibility
`main.v`	CLI entry point
`scanner.v`	Filesystem scanning
`project.v`	Project data structures
`languages.v`	Language detection
`output.v`	Terminal output and formatting
`v.mod`	V module definition

As Atlas grows, the internal architecture will evolve with it.

Design Philosophy

Atlas follows a few principles.

Useful before intelligent

Atlas should provide useful information without requiring AI, remote services, or external infrastructure.

The first layer of Atlas is therefore: deterministic, local, and explainable.

Progressive understanding

Atlas does not need to understand everything about a codebase immediately.

It starts with:

Files
  ↓
Structure
  ↓
Dependencies
  ↓
Symbols
  ↓
Relationships
  ↓
Understanding

Each layer builds on the previous one.

CLI first

Atlas is designed to work naturally from a terminal.

No dashboard.
No web server.
No database.
No account.
No unnecessary infrastructure.

Just point it at a project and inspect the result.

Small core

The project should remain lightweight enough to run comfortably on a developer's machine.

Complexity should be introduced because it provides meaningful information, not simply because it is technically possible.

Future: `atlas explain`

One of Atlas's long-term goals is to provide structural explanations of files and components.

For example:

scanner.v
────────────────────────────────

Purpose
  Project filesystem scanner

Language
  V

Size
  184 lines
  4.82 KB

Imports
  os
  io

Symbols
  scan_project()
  scan_directory()
  count_lines()

Dependencies
  project.v
  languages.v

Used by
  main.v

Structure
  3 functions
  0 structs
  0 constants

Behavior
  • Traverses directories recursively
  • Identifies files and directories
  • Collects file size and line count
  • Builds the Project representation

This does not necessarily require an AI model.

Atlas can derive a surprising amount of information from the structure of a program itself.

If local AI capabilities are introduced in the future, they can remain an optional layer rather than becoming a requirement for the core tool.

Development

Run Atlas directly from the repository:

v run .

Build it:

v .

The project is written in V and currently keeps its source files in the module root.

Contributing

Atlas is currently a personal project in active development.

Contributions, ideas, bug reports, and discussions are welcome as the project matures.

Before submitting a larger change, consider opening an issue to discuss the approach first.

When contributing, try to keep changes:

Focused
Small
Deterministic
Easy to understand
Consistent with Atlas's CLI-first philosophy

License

Atlas is released under the MIT License.

See LICENSE for the complete license text.

Atlas 🗺️
_{Map your codebase. Understand your project.}

Name		Name	Last commit message	Last commit date
.github		.github
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
constants.v		constants.v
extension_stats.v		extension_stats.v
file_types.v		file_types.v
languages.v		languages.v
main.v		main.v
output.v		output.v
project.v		project.v
scanner.v		scanner.v
scanner_linux.c.v		scanner_linux.c.v
scanner_test.v		scanner_test.v
statistics.v		statistics.v
tree.v		tree.v
utils.v		utils.v
v.mod		v.mod

Latest commit

History

Folders and files

Repository files navigation

Atlas

What is Atlas?

Example

Why Atlas?

Features

Current

Coming later

Installation

Requirements

Clone the repository

Build Atlas

Development mode

Usage

Analyze the current directory

Analyze another project

Output

Project information

Languages

Supported languages

Roadmap

v0.1 • Explorer

v0.2 • Structure

v0.3 • Dependencies

v0.4 • Symbols

v0.5+ • Relationships

v1.0 • Codebase Intelligence

Architecture

Project Structure

Design Philosophy

Useful before intelligent

Progressive understanding

CLI first

Small core

Future: atlas explain

Development

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Future: `atlas explain`